diff --git a/.openapi.json.swp b/.openapi.json.swp new file mode 100644 index 0000000..64a00da Binary files /dev/null and b/.openapi.json.swp differ diff --git a/Cargo.lock b/Cargo.lock index bac76b0..c9395a1 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -174,6 +174,7 @@ dependencies = [ "reqwest", "serde", "serde_json", + "serde_path_to_error", "serde_yaml", "strum 0.23.0", "strum_macros 0.23.1", @@ -183,9 +184,7 @@ dependencies = [ [[package]] name = "cherrybomb-oas" -version = "0.1.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "69dec5274a0a239037855a6e6753a093e9690522c6883f2a8bc9288a70b86a68" +version = "0.1.1" dependencies = [ "colored", "serde", @@ -976,6 +975,16 @@ dependencies = [ "serde", ] +[[package]] +name = "serde_path_to_error" +version = "0.1.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4beec8bce849d58d06238cb50db2e1c417cfeafa4c63f692b15c82b7c80f8335" +dependencies = [ + "itoa", + "serde", +] + [[package]] name = "serde_urlencoded" version = "0.7.1" diff --git a/cherrybomb-engine/Cargo.toml b/cherrybomb-engine/Cargo.toml index 0162c6f..99bcbbf 100644 --- a/cherrybomb-engine/Cargo.toml +++ b/cherrybomb-engine/Cargo.toml @@ -13,7 +13,7 @@ edition = "2021" # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html [dependencies] -cherrybomb-oas = "^0.1" +cherrybomb-oas = {path="../cherrybomb-oas"} anyhow = "1.0.66" thiserror = "1.0.37" serde_json = "^1.0" @@ -25,3 +25,4 @@ strum_macros = "0.23" # legacy url="^2" #legacy base64 = "0.13" #legacy reqwest = { version = "^0.11",default_features = false, features = ["json","rustls-tls"] } #legacy +serde_path_to_error = "0.1.14" diff --git a/cherrybomb-engine/src/.lib.rs.swp b/cherrybomb-engine/src/.lib.rs.swp deleted file mode 100644 index 5e302d6..0000000 Binary files a/cherrybomb-engine/src/.lib.rs.swp and /dev/null differ diff --git a/cherrybomb-engine/src/lib.rs b/cherrybomb-engine/src/lib.rs index 0124664..d4855a7 100644 --- a/cherrybomb-engine/src/lib.rs +++ b/cherrybomb-engine/src/lib.rs @@ -17,6 +17,7 @@ use std::vec; use strum::IntoEnumIterator; use serde_yaml; use anyhow::anyhow; +use serde_path_to_error::deserialize; fn verbose_print(config: &Config, required: Option, message: &str) { let required = required.unwrap_or(Verbosity::Normal); @@ -52,6 +53,11 @@ pub async fn run(config: &mut Config) -> anyhow::Result { } _ => return Err(anyhow::Error::msg("Unsupported config file extension")), }; + let r :Result = deserialize(&oas_json); + let oas = match r { + Ok(oas) => oas, + Err(e) => return Err(anyhow::Error::msg(format!("Error creating OAS struct: {}", e))), + }; let oas: OAS3_1 = match serde_json::from_value(oas_json.clone().into()) { Ok(oas) => oas, Err(e) => return Err(anyhow::Error::msg(format!("Error creating OAS struct: {}", e))), diff --git a/cherrybomb-engine/src/scan/active/.active_scanner.rs.swp b/cherrybomb-engine/src/scan/active/.utils.rs.swp similarity index 50% rename from cherrybomb-engine/src/scan/active/.active_scanner.rs.swp rename to cherrybomb-engine/src/scan/active/.utils.rs.swp index 44122ff..df32df0 100644 Binary files a/cherrybomb-engine/src/scan/active/.active_scanner.rs.swp and b/cherrybomb-engine/src/scan/active/.utils.rs.swp differ diff --git a/cherrybomb-engine/src/scan/active/active_scanner.rs b/cherrybomb-engine/src/scan/active/active_scanner.rs index edee0b6..ed14129 100644 --- a/cherrybomb-engine/src/scan/active/active_scanner.rs +++ b/cherrybomb-engine/src/scan/active/active_scanner.rs @@ -212,7 +212,7 @@ impl Deserialize<'de>> ActiveScan { pub fn gen_default_value(schema: Box) -> Value { let ret: Value = if let Some(data_type) = schema.schema_type { - match data_type.as_str() { + match data_type.as_str().as_str() { "string" => { if let Some(num) = schema.min_length { json!(iter::repeat(['B', 'L', 'S', 'T']) diff --git a/cherrybomb-engine/src/scan/active/additional_checks.rs b/cherrybomb-engine/src/scan/active/additional_checks.rs index 35c1a55..83dd310 100644 --- a/cherrybomb-engine/src/scan/active/additional_checks.rs +++ b/cherrybomb-engine/src/scan/active/additional_checks.rs @@ -4,6 +4,7 @@ use crate::active::utils::create_payload; use crate::scan::Level; use cherrybomb_oas::legacy::legacy_oas::OAS; use cherrybomb_oas::legacy::utils::Method; +use cherrybomb_oas::legacy::schema::SchemaTypes; use serde::Serialize; use serde_json::{json, Value}; use std::collections::{HashMap, HashSet}; @@ -856,10 +857,11 @@ impl ActiveScan { { let mut _value_to_send = "2".to_string(); let mut var_int: i32 = 2; - if types == *"integer".to_string() { + let type_str = "integer".to_string(); + if matches!(types, SchemaTypes::Str(type_str)) { if let Some(val) = i.inner(&self.oas_value).examples { if let Some((_ex, val)) = val.into_iter().next() { - _value_to_send = val.value.to_string(); + _value_to_send = val.inner(&self.oas_value).value.to_string(); var_int = _value_to_send.parse::().unwrap(); } } diff --git a/cherrybomb-engine/src/scan/active/utils.rs b/cherrybomb-engine/src/scan/active/utils.rs index 510892d..df52c12 100644 --- a/cherrybomb-engine/src/scan/active/utils.rs +++ b/cherrybomb-engine/src/scan/active/utils.rs @@ -146,14 +146,14 @@ pub fn create_payload_for_get( if let Some(value) = parameter.examples { // if there is an example if let Some((_ex, val)) = value.into_iter().next() { - option_example_value = Some(val.value.to_string()); + option_example_value = Some(val.inner(swagger).value.to_string()); } } if let Some(schema_ref) = parameter.schema { // dbg!(&schema_ref); if let Some(schema_type) = schema_ref.inner(swagger).schema_type { // let val_to_path:String; - match schema_type.as_str() { + match schema_type.as_str().as_str() { "string" => { let mut example_value = "randomString".to_string(); if let Some(val) = option_example_value { @@ -224,11 +224,11 @@ pub fn create_payload_for_get( if let Some(values) = parameter.examples { if let Some((_ex, val)) = values.into_iter().next() { //take example as value - final_value = val.value.to_string(); + final_value = val.inner(swagger).value.to_string(); params_vec.push(RequestParameter { name: param_name, dm: QuePay::Query, - value: val.value.to_string(), + value:final_value.clone(), }); } else { //if no examples insert randonstring diff --git a/cherrybomb-engine/src/scan/passive/utils.rs b/cherrybomb-engine/src/scan/passive/utils.rs index 588dec3..df5317f 100644 --- a/cherrybomb-engine/src/scan/passive/utils.rs +++ b/cherrybomb-engine/src/scan/passive/utils.rs @@ -230,9 +230,9 @@ pub fn param_enum_rec(param: &Param, loc: String) -> Vec { } pub fn additional_properties_test(schema: &Schema, location: String) -> Vec { let tp = if let Some(t) = &schema.schema_type { - t + t.as_str() } else { - "" + String::new() }; let mut alerts = vec![]; match tp.to_lowercase().as_str() { @@ -343,9 +343,9 @@ pub fn get_all_params_by_type( ) -> Vec<(Schema, String)> { let mut schemas = vec![]; let s_tp = if let Some(t) = &schema.schema_type { - t + t.as_str() } else { - "" + String::new() }; if s_tp == tp { schemas.push((schema.clone(), location.clone())); diff --git a/cherrybomb-oas/src/legacy/.legacy_oas.rs.swp b/cherrybomb-oas/src/legacy/.legacy_oas.rs.swp new file mode 100644 index 0000000..2643cfe Binary files /dev/null and b/cherrybomb-oas/src/legacy/.legacy_oas.rs.swp differ diff --git a/cherrybomb-oas/src/legacy/.param.rs.swp b/cherrybomb-oas/src/legacy/.param.rs.swp new file mode 100644 index 0000000..d312550 Binary files /dev/null and b/cherrybomb-oas/src/legacy/.param.rs.swp differ diff --git a/cherrybomb-oas/src/legacy/.path.rs.swp b/cherrybomb-oas/src/legacy/.path.rs.swp new file mode 100644 index 0000000..9cfaa64 Binary files /dev/null and b/cherrybomb-oas/src/legacy/.path.rs.swp differ diff --git a/cherrybomb-oas/src/legacy/.refs.rs.swp b/cherrybomb-oas/src/legacy/.refs.rs.swp new file mode 100644 index 0000000..8bc069f Binary files /dev/null and b/cherrybomb-oas/src/legacy/.refs.rs.swp differ diff --git a/cherrybomb-oas/src/legacy/.schema.rs.swp b/cherrybomb-oas/src/legacy/.schema.rs.swp new file mode 100644 index 0000000..5b691bb Binary files /dev/null and b/cherrybomb-oas/src/legacy/.schema.rs.swp differ diff --git a/cherrybomb-oas/src/legacy/legacy_oas.rs b/cherrybomb-oas/src/legacy/legacy_oas.rs index 37c7454..07b55f6 100644 --- a/cherrybomb-oas/src/legacy/legacy_oas.rs +++ b/cherrybomb-oas/src/legacy/legacy_oas.rs @@ -48,7 +48,7 @@ pub struct Server { pub type Security = HashMap>; pub type Callback = HashMap>; pub type Content = HashMap; -pub type Examples = HashMap; +pub type Examples = HashMap; pub type EncodingMap = HashMap; //Practicaly Any //type Schema = Value; diff --git a/cherrybomb-oas/src/legacy/param.rs b/cherrybomb-oas/src/legacy/param.rs index cbb19da..d755852 100644 --- a/cherrybomb-oas/src/legacy/param.rs +++ b/cherrybomb-oas/src/legacy/param.rs @@ -95,7 +95,7 @@ impl ParamInt { } } } -#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default)] +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Default)] pub struct ParamString { min_length: i64, max_length: i64, @@ -137,7 +137,7 @@ impl Default for ParamValue { impl ParamValue { pub fn from(schema: &Schema) -> Self { let v = if let Some(t) = schema.schema_type.clone() { - t + t.as_str().to_lowercase() } else { String::new() }; @@ -327,7 +327,7 @@ impl Param { } pub fn schema_rec(swagger: &Value, schema: Schema, required: bool) -> Self { let p_type = if let Some(t) = schema.schema_type.clone() { - t + t.as_str().to_lowercase() } else { String::new() }; @@ -382,7 +382,7 @@ impl Param { } for schema in schemas { let p_type = if let Some(t) = schema.schema_type.clone() { - t + t.as_str().to_lowercase() } else { String::new() }; diff --git a/cherrybomb-oas/src/legacy/path.rs b/cherrybomb-oas/src/legacy/path.rs index 5a52115..9735f1b 100644 --- a/cherrybomb-oas/src/legacy/path.rs +++ b/cherrybomb-oas/src/legacy/path.rs @@ -67,7 +67,7 @@ impl Operation { vec![] }; let p_type = if let Some(t) = inner.schema_type.clone() { - t + t.as_str().to_lowercase() } else { String::new() }; diff --git a/cherrybomb-oas/src/legacy/refs.rs b/cherrybomb-oas/src/legacy/refs.rs index 5dcf0bc..94b30af 100644 --- a/cherrybomb-oas/src/legacy/refs.rs +++ b/cherrybomb-oas/src/legacy/refs.rs @@ -197,3 +197,23 @@ impl CallbackRef { } } } +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)] +#[serde(untagged)] +pub enum ExampleRef { + Ref(Reference), + Example(Box), +} +impl Default for ExampleRef { + fn default() -> Self { + Self::Ref(Reference::default()) + } +} +#[allow(unused)] +impl ExampleRef { + pub fn inner(&self, swagger: &Value) -> Example { + match self { + Self::Example(p) => *p.clone(), + Self::Ref(r) => r.get::(swagger), + } + } +} diff --git a/cherrybomb-oas/src/legacy/schema.rs b/cherrybomb-oas/src/legacy/schema.rs index 21b817f..811c476 100644 --- a/cherrybomb-oas/src/legacy/schema.rs +++ b/cherrybomb-oas/src/legacy/schema.rs @@ -2,13 +2,15 @@ use super::refs::*; use serde::{Deserialize, Serialize}; use serde_json::Value; use std::collections::HashMap; +use std::fmt; -#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)] #[serde(untagged)] pub enum SchemaStrInt { Int(i64), Str(String), Bool(bool), + Float(f64), } impl Default for SchemaStrInt { fn default() -> Self { @@ -26,6 +28,27 @@ impl Default for AddProps { Self::Bool(true) } } +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] +#[serde(untagged)] +pub enum SchemaTypes { + Str(String), + Arr(Vec), + Obj(HashMap), +} +impl SchemaTypes{ + pub fn as_str(&self)->String{ + match self{ + Self::Str(s) => s.to_string(), + Self::Arr(v) => v[0].to_string(), + Self::Obj(h) => h.get("type").unwrap().to_string(), + } + } +} +impl fmt::Display for SchemaTypes { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + write!(f, "{}", self.as_str()) + } +} #[derive(Debug, Clone, Serialize, Deserialize, Default, PartialEq)] pub struct Schema { pub title: Option, @@ -41,9 +64,9 @@ pub struct Schema { pub min_length: Option, //String - STAY AWAY!(regex) pub pattern: Option, - #[serde(rename = "maxItem")] + #[serde(rename = "maxItems")] pub max_items: Option, - #[serde(rename = "minItem")] + #[serde(rename = "minItems")] pub min_items: Option, #[serde(rename = "uniqueItem")] pub unique_items: Option, @@ -57,7 +80,7 @@ pub struct Schema { #[serde(rename = "enum")] pub schema_enum: Option>>, #[serde(rename = "type")] - pub schema_type: Option, + pub schema_type: Option, #[serde(rename = "allOf")] pub all_of: Option>, #[serde(rename = "oneOf")] diff --git a/oas.json b/oas.json deleted file mode 100644 index e99ece1..0000000 --- a/oas.json +++ /dev/null @@ -1 +0,0 @@ -{"openapi": "3.0.1", "info": {"title": "snap-auth-api-release", "version": "2023-06-26T21:47:50Z"}, "servers": [{"url": "https://auth-release.snap-engineering.us"}], "paths": {"/passwordless/start": {"post": {}, "options": {"responses": {"200": {"description": "200 response", "headers": {"Access-Control-Allow-Origin": {"schema": {"type": "string"}}, "Access-Control-Allow-Methods": {"schema": {"type": "string"}}, "Access-Control-Allow-Headers": {"schema": {"type": "string"}}}, "content": {}}}}}, "/passwordless/verify": {"post": {}, "options": {"responses": {"200": {"description": "200 response", "headers": {"Access-Control-Allow-Origin": {"schema": {"type": "string"}}, "Access-Control-Allow-Methods": {"schema": {"type": "string"}}, "Access-Control-Allow-Headers": {"schema": {"type": "string"}}}, "content": {}}}}}, "/oauth/token": {"post": {}, "options": {"responses": {"200": {"description": "200 response", "headers": {"Access-Control-Allow-Origin": {"schema": {"type": "string"}}, "Access-Control-Allow-Methods": {"schema": {"type": "string"}}, "Access-Control-Allow-Headers": {"schema": {"type": "string"}}}, "content": {}}}}}}, "components": {}} \ No newline at end of file diff --git a/openapi.json b/openapi.json new file mode 100644 index 0000000..bea9320 --- /dev/null +++ b/openapi.json @@ -0,0 +1,14240 @@ +{ + "openapi": "3.1.0", + "info": { + "version": "2.0.0", + "title": "Lichess.org API reference", + "contact": { + "name": "Lichess.org API", + "url": "https://lichess.org/api", + "email": "contact@lichess.org" + }, + "x-logo": { + "url": "https://lichess1.org/assets/logo/lichess-pad12.svg" + }, + "license": { + "name": "AGPL-3.0-or-later", + "url": "https://www.gnu.org/licenses/agpl-3.0.txt" + }, + "description": "# Introduction\nWelcome to the reference for the Lichess API! Lichess is free/libre,\nopen-source chess server powered by volunteers and donations.\n- Get help in the [Lichess Discord channel](https://discord.gg/lichess)\n- API demo app with OAuth2 login, gameplay, and more: [source](https://github.com/lichess-org/api-demo) / [demo](https://lichess-org.github.io/api-demo/)\n- [Contribute to this documentation on Github](https://github.com/lichess-org/api)\n- Check out [Lichess widgets to embed in your website](https://lichess.org/developers)\n- [Download all Lichess rated games](https://database.lichess.org/)\n- [Download all Lichess puzzles with themes, ratings and votes](https://database.lichess.org/#puzzles)\n\n## Endpoint\nAll requests go to `https://lichess.org` (unless otherwise specified).\n\n## Clients\n- [Python general API](https://github.com/ZackClements/berserk)\n- [MicroPython general API](https://github.com/mkomon/uberserk)\n- [Python general API - async](https://pypi.org/project/async-lichess-sdk)\n- [Python Lichess Bot](https://github.com/lichess-bot-devs/lichess-bot)\n- [Python Board API for Certabo](https://github.com/haklein/certabo-lichess)\n- [Java general API](https://github.com/tors42/chariot)\n\n## Rate limiting\nAll requests are rate limited using various strategies,\nto ensure the API remains responsive for everyone.\nOnly make one request at a time.\nIf you receive an HTTP response with a [429 status](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#429),\nplease wait a full minute before resuming API usage.\n\n## Streaming with ND-JSON\nSome API endpoints stream their responses as [Newline Delimited JSON a.k.a. **nd-json**](http://ndjson.org/), with one JSON object per line.\n\nHere's a [JavaScript utility function](https://gist.github.com/ornicar/a097406810939cf7be1df8ea30e94f3e) to help reading NDJSON streamed responses.\n\n## Authentication\n### Which authentication method is right for me?\n[Read about the Lichess API authentication methods and code examples](https://github.com/lichess-org/api/blob/master/example/README.md)\n\n### Personal Access Token\nPersonal API access tokens allow you to quickly interact with Lichess API without going through an OAuth flow.\n- [Generate a personal access token](https://lichess.org/account/oauth/token)\n- `curl https://lichess.org/api/account -H \"Authorization: Bearer {token}\"`\n- [NodeJS example](https://github.com/lichess-org/api/tree/master/example/oauth-personal-token)\n\n### Authorization Code Flow with PKCE\nThe authorization code flow with PKCE allows your users to **login with Lichess**.\nLichess supports unregistered and public clients (no client authentication, choose any unique client id).\nThe only accepted code challenge method is `S256`.\nAccess tokens are long-lived (expect one year), unless they are revoked.\nRefresh tokens are not supported.\n\nSee the [documentation for the OAuth endpoints](#tag/OAuth) or\nthe [PKCE RFC](https://datatracker.ietf.org/doc/html/rfc7636#section-4) for a precise protocol description.\n\n- [Demo app](https://lichess-org.github.io/api-demo/)\n- [Minimal client-side example](https://github.com/lichess-org/api/tree/master/example/oauth-app)\n- [Flask/Python example](https://github.com/lakinwecker/lichess-oauth-flask)\n- [Java example](https://github.com/tors42/lichess-oauth-pkce-app)\n- [NodeJS Passport strategy to login with Lichess OAuth2](https://www.npmjs.com/package/passport-lichess)\n\n#### Real life examples\n- [PyChess](https://github.com/gbtami/pychess-variants) ([source code](https://github.com/gbtami/pychess-variants))\n- [Lichess4545](https://www.lichess4545.com/) ([source code](https://github.com/cyanfish/heltour))\n- [English Chess Federation](https://ecf.octoknight.com/)\n- [Rotherham Online Chess](https://rotherhamonlinechess.azurewebsites.net/tournaments)\n\n### Token format\nAccess tokens and authorization codes match `^[A-Za-z0-9_]+$`.\nThe length of tokens can be increased without notice. Make sure your application can handle at least 512 characters.\nBy convention tokens have a recognizable prefix, but do not rely on this.\n" + }, + "servers": [ + { + "url": "https://lichess.org" + } + ], + "tags": [ + { + "name": "Account", + "description": "Read and write account information and preferences.\n\n" + }, + { + "name": "Users", + "description": "Access registered users on Lichess.\n\n\n- Each user blog exposes an atom (RSS) feed, like \n- User blogs mashup feed: https://lichess.org/blog/community.atom\n- User blogs mashup feed for a language: https://lichess.org/blog/community/fr.atom\n" + }, + { + "name": "Relations", + "description": "Access relations between users.\n" + }, + { + "name": "Games", + "description": "Access games played on Lichess.\n\n" + }, + { + "name": "TV", + "description": "Access Lichess TV channels and games.\n & \n" + }, + { + "name": "Puzzles", + "description": "Access Lichess [puzzle history and dashboard](https://lichess.org/training).\n\nOur collection of puzzles is in the public domain, you can [download it here](https://database.lichess.org/#puzzles).\nFor a list of our puzzle themes with their description, check out the [theme translation file](https://github.com/ornicar/lila/blob/master/translation/source/puzzleTheme.xml).\nThe daily puzzle can be [posted in your slack workspace](https://lichess.org/daily-puzzle-slack).\n" + }, + { + "name": "Teams", + "description": "Access and manage Lichess teams and their members.\n\n" + }, + { + "name": "Board", + "description": "Play on Lichess with physical boards and third-party clients.\n Works with normal Lichess accounts. Engine play or assistance is [forbidden](https://lichess.org/page/fair-play).\n\n\n### Features\n - [Stream incoming chess moves](#operation/boardGameStream)\n - [Play chess moves](#operation/boardGameMove)\n - [Read](#operation/boardGameStream) and [write](#operation/boardGameChatPost) in the player and spectator chats\n - [Receive](#operation/apiStreamEvent), [create](#operation/challengeCreate) and [accept](#operation/challengeAccept) (or [decline](#operation/challengeDecline)) challenges\n - [Abort](#operation/boardGameAbort) and [resign](#operation/boardGameResign) games\n - Compatible with normal Lichess accounts\n\n \n### Restrictions\n - Engine assistance, or any kind of outside help, is [forbidden](https://lichess.org/page/fair-play)\n - Time controls: [Rapid, Classical and Correspondence](https://lichess.org/faq#time-controls) only.\n For direct challenges and games vs AI, Blitz is also possible.\n\n### Links\n - [Announcement](https://lichess.org/blog/XlRW5REAAB8AUJJ-/welcome-lichess-boards)\n - [Implementation example](https://github.com/lichess-org/api-demo) and [live demo](https://lichess-org.github.io/api-demo/)\n\n - [Certabo support](https://github.com/haklein/certabo-lichess)\n - [Lichs (play from command-line)](https://github.com/Cqsi/lichs)\n - [Lichess discord bot](https://top.gg/bot/707287095911120968)\n - [cli-chess](https://github.com/trevorbayless/cli-chess/)" + }, + { + "name": "Bot", + "description": "Play on Lichess as a bot. Allows engine play.\n Read the [blog post announcement of lichess bots](https://lichess.org/blog/WvDNticAAMu_mHKP/welcome-lichess-bots).\n\n Only works with [Bot accounts](#operation/botAccountUpgrade).\n\n\n### Features\n - [Stream incoming chess moves](#operation/botGameStream)\n - [Play chess moves](#operation/botGameMove)\n - [Read](#operation/botGameStream) and [write](#operation/botGameChat) in the player and spectator chats\n - [Receive](#operation/apiStreamEvent), [create](#operation/challengeCreate) and [accept](#operation/challengeAccept) (or [decline](#operation/challengeDecline)) challenges\n - [Abort](#operation/botGameAbort) and [resign](#operation/botGameResign) games\n - Engine assistance is [allowed](https://lichess.org/page/fair-play)\n\n### Restrictions\n - Bots can only play challenge games: pools and tournaments are off-limits\n - Bots cannot play UltraBullet (¼+0) because it requires making too many requests. But 0+1 and ½+0 are allowed.\n\n### Integrations\n - [Python3 lichess-bot](https://github.com/ShailChoksi/lichess-bot) (official)\n - [JavaScript bot-o-tron](https://github.com/tailuge/bot-o-tron)\n - [Golang lichess-bot](https://github.com/dolegi/lichess-bot)\n - [Electronic Chessboard](http://www.oliviermercier.com/res/projects/chessboard/) - Yours? Please make [an issue or pull request](https://github.com/lichess-org/api).\n\n### Links\n - [Announcement](https://lichess.org/blog/WvDNticAAMu_mHKP/welcome-lichess-bots)\n - Join the [Lichess Bots team](https://lichess.org/team/lichess-bots) with your bot account\n - [Get help in the discord channel](https://discord.gg/quwueFd)\n - Watch [Lichess Bot TV](https://lichess.org/tv/bot)" + }, + { + "name": "Challenges", + "description": "Send and receive challenges to play.\n\nTo create a lot of challenges, consider [bulk pairing](#operation/bulkPairingCreate) instead.\n" + }, + { + "name": "Bulk pairings", + "description": "Create many games for other players.\n\nThese endpoints are intended for tournament organisers.\n" + }, + { + "name": "Arena tournaments", + "description": "Access Arena tournaments played on Lichess.\n[Official Arena tournaments](https://lichess.org/tournament) are maintained by Lichess,\nbut you can [create your own Arena tournaments](https://lichess.org/tournament/new) as well.\n" + }, + { + "name": "Swiss tournaments", + "description": "Access Swiss tournaments played on Lichess.\n[Read more about Swiss tournaments.](https://lichess.org/swiss).\n" + }, + { + "name": "Simuls", + "description": "Access simuls played on Lichess.\n\n" + }, + { + "name": "Studies", + "description": "Access Lichess studies.\n\n" + }, + { + "name": "Messaging", + "description": "Private messages with other players.\n\n" + }, + { + "name": "Broadcasts", + "description": "Relay chess events on Lichess.\n[Official broadcasts](https://lichess.org/broadcast) are maintained by Lichess,\nbut you can [create your own broadcasts](https://lichess.org/broadcast/new) to cover any live game or chess event.\nYou will need to publish PGN on a public URL so that Lichess can pull updates from it.\nAlternatively, you can push PGN updates to Lichess using this API.\n\nBroadcasts are organized in tournaments, which have several rounds, which have several games.\nYou must first create a tournament, then you can add rounds to them.\n" + }, + { + "name": "Analysis", + "description": "Access Lichess cloud evaluations database.\n\n" + }, + { + "name": "External engine", + "description": "**This API is in alpha and subject to change.**\n\nUse or provide external engine analysis.\n\nExternal engines can provide analysis on pages like the\n[analysis board](https://lichess.org/analysis), running as a service\noutside of the browser, or even on a different machine.\n" + }, + { + "name": "Opening Explorer", + "description": "Lookup positions from the [Lichess opening explorer](https://lichess.org/analysis#explorer).\n\nRuns .\n\n**The endpoint hostname is not lichess.org but explorer.lichess.ovh.**\n" + }, + { + "name": "Tablebase", + "description": "Lookup positions from the [Lichess tablebase server](https://lichess.org/blog/W3WeMyQAACQAdfAL/7-piece-syzygy-tablebases-are-complete).\n\n**The endpoint hostname is not lichess.org but tablebase.lichess.ovh.**\n" + }, + { + "name": "OAuth", + "description": "Obtaining and revoking OAuth tokens.\n\n[Read about the Lichess API authentication methods and code examples](https://github.com/lichess-org/api/blob/master/example/README.md).\n" + } + ], + "paths": { + "/api/users/status": { + "get": { + "operationId": "apiUsersStatus", + "summary": "Get real-time users status", + "description": "Read the `online`, `playing` and `streaming` flags of several users.\n\nThis API is very fast and cheap on lichess side.\nSo you can call it quite often (like once every 5 seconds).\n\nUse it to track players and know when they're connected on lichess and playing games.\n", + "tags": [ + "Users" + ], + "security": [], + "parameters": [ + { + "in": "query", + "name": "ids", + "required": true, + "description": "User IDs separated by commas. Up to 100 IDs.", + "schema": { + "type": "string" + }, + "example": "aliquantus,chess-network,lovlas" + }, + { + "in": "query", + "name": "withGameIds", + "required": false, + "description": "Also return the ID of the game being played, if any, for each player, in a `playingId` field.\nDefaults to `false` to preserve server resources.\n", + "schema": { + "type": "boolean" + }, + "example": true + } + ], + "responses": { + "200": { + "description": "The list of users and their respective statuses.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "name": { + "type": "string" + }, + "title": { + "type": "string" + }, + "online": { + "type": "boolean" + }, + "playing": { + "type": "boolean" + }, + "streaming": { + "type": "boolean" + }, + "patron": { + "type": "boolean" + } + }, + "required": [ + "id", + "name" + ] + }, + "example": [ + { + "id": "aliquantus", + "name": "Aliquantus" + }, + { + "id": "chess-network", + "name": "Chess-Network", + "title": "NM", + "online": true, + "playing": true, + "streaming": true, + "patron": true + } + ] + } + } + } + } + } + } + }, + "/api/player": { + "get": { + "operationId": "player", + "summary": "Get all top 10", + "tags": [ + "Users" + ], + "security": [], + "description": "Get the top 10 players for each speed and variant.\n\nSee .\n", + "responses": { + "200": { + "description": "The list of variants with their respective top players.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Top10s" + } + } + } + } + } + } + }, + "/api/player/top/{nb}/{perfType}": { + "get": { + "operationId": "playerTopNbPerfType", + "summary": "Get one leaderboard", + "tags": [ + "Users" + ], + "security": [], + "description": "Get the leaderboard for a single speed or variant (a.k.a. `perfType`).\nThere is no leaderboard for correspondence or puzzles.\n\nSee .\n", + "parameters": [ + { + "in": "path", + "name": "nb", + "description": "How many users to fetch", + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 200, + "example": 100 + }, + "required": true + }, + { + "in": "path", + "name": "perfType", + "description": "The speed or variant", + "schema": { + "type": "string", + "example": "bullet", + "enum": [ + "ultraBullet", + "bullet", + "blitz", + "rapid", + "classical", + "chess960", + "crazyhouse", + "antichess", + "atomic", + "horde", + "kingOfTheHill", + "racingKings", + "threeCheck" + ] + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The list of top players for the variant.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/vnd.lichess.v3+json": { + "schema": { + "$ref": "#/components/schemas/Leaderboard" + } + } + } + } + } + } + }, + "/api/user/{username}": { + "get": { + "operationId": "apiUser", + "summary": "Get user public data", + "description": "Read public data of a user.\n\nIf the request is [authenticated with OAuth2](#section/Introduction/Authentication),\nthen extra fields might be present in the response: `followable`, `following`, `blocking`, `followsYou`.\n", + "tags": [ + "Users" + ], + "security": [ + { + "OAuth2": [] + } + ], + "parameters": [ + { + "in": "path", + "name": "username", + "schema": { + "type": "string" + }, + "required": true + }, + { + "in": "query", + "name": "trophies", + "description": "Include user trophies", + "schema": { + "type": "boolean", + "default": false + } + } + ], + "responses": { + "200": { + "description": "The information of the user.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UserExtended" + } + } + } + } + } + } + }, + "/api/user/{username}/rating-history": { + "get": { + "operationId": "apiUserRatingHistory", + "summary": "Get rating history of a user", + "description": "Read rating history of a user, for all perf types.\nThere is at most one entry per day.\nFormat of an entry is `[year, month, day, rating]`.\n`month` starts at zero (January).\n", + "tags": [ + "Users" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "username", + "schema": { + "type": "string" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The rating history of the user.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RatingHistory" + } + } + } + } + } + } + }, + "/api/user/{username}/perf/{perf}": { + "get": { + "operationId": "apiUserPerf", + "summary": "Get performance statistics of a user", + "description": "Read performance statistics of a user, for a single performance.\nSimilar to the [performance pages on the website](https://lichess.org/@/thibault/perf/bullet).\n", + "tags": [ + "Users" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "username", + "schema": { + "type": "string" + }, + "required": true + }, + { + "in": "path", + "name": "perf", + "schema": { + "$ref": "#/components/schemas/PerfType" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The performance statistics of the user", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PerfStat" + } + } + } + } + } + } + }, + "/api/user/{username}/activity": { + "get": { + "operationId": "apiUserActivity", + "summary": "Get user activity", + "description": "Read data to generate the activity feed of a user.\n", + "tags": [ + "Users" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "username", + "schema": { + "type": "string" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The activity feed of the user.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "example": "https://gist.github.com/ornicar/0ee2d2427cb74ed1a35e86f5ba09fabc" + } + } + } + } + } + }, + "/api/puzzle/daily": { + "get": { + "operationId": "apiPuzzleDaily", + "summary": "Get the daily puzzle", + "description": "Get the daily Lichess puzzle in JSON format.\n\nAlternatively, you can [post it in your slack workspace](https://lichess.org/daily-puzzle-slack).\n", + "tags": [ + "Puzzles" + ], + "security": [], + "responses": { + "200": { + "description": "The daily puzzle.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PuzzleJson" + } + } + } + } + } + } + }, + "/api/puzzle/{id}": { + "get": { + "operationId": "apiPuzzleId", + "summary": "Get a puzzle by its ID", + "description": "Get a single Lichess puzzle in JSON format.", + "tags": [ + "Puzzles" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "id", + "required": true, + "description": "The puzzle ID", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The requested puzzle.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PuzzleJson" + } + } + } + } + } + } + }, + "/api/puzzle/activity": { + "get": { + "operationId": "apiPuzzleActivity", + "summary": "Get your puzzle activity", + "description": "Download your puzzle activity in [ndjson](#section/Introduction/Streaming-with-ND-JSON) format.\n\nPuzzle activity is sorted by reverse chronological order (most recent first)\n\nWe recommend streaming the response, for it can be very long.\n", + "tags": [ + "Puzzles" + ], + "security": [ + { + "OAuth2": [ + "puzzle:read" + ] + } + ], + "parameters": [ + { + "in": "query", + "name": "max", + "description": "How many entries to download. Leave empty to download all activity.", + "schema": { + "type": "integer", + "minimum": 1 + } + } + ], + "responses": { + "200": { + "description": "The puzzle activity of the logged in user.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/x-ndjson": { + "schema": { + "$ref": "#/components/schemas/PuzzleRoundJson" + } + } + } + } + } + } + }, + "/api/puzzle/dashboard/{days}": { + "get": { + "operationId": "apiPuzzleDashboard", + "summary": "Get your puzzle dashboard", + "description": "Download your [puzzle dashboard](https://lichess.org/training/dashboard/30/dashboard) as JSON.\n\nAlso includes all puzzle themes played, with aggregated results.\n\nAllows re-creating the [improvement/strengths](https://lichess.org/training/dashboard/30/improvementAreas) interfaces.\n", + "tags": [ + "Puzzles" + ], + "security": [ + { + "OAuth2": [ + "puzzle:read" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "days", + "required": true, + "description": "How many days to look back when aggregating puzzle results. 30 is sensible.", + "schema": { + "type": "integer", + "minimum": 1 + } + } + ], + "responses": { + "200": { + "description": "The puzzle dashboard of the logged in user.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PuzzleDashboardJson" + } + } + } + } + } + } + }, + "/api/storm/dashboard/{username}": { + "get": { + "operationId": "apiStormDashboard", + "summary": "Get the storm dashboard of a player", + "description": "Download the [storm dashboard](https://lichess.org/storm/dashboard/mrbasso) of any player as JSON.\n\nContains the aggregated highscores, and the history of storm runs aggregated by days.\n\nUse `?days=0` if you only care about the highscores.\n", + "tags": [ + "Puzzles" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "username", + "description": "Username of the player", + "schema": { + "type": "string" + }, + "required": true + }, + { + "in": "query", + "name": "days", + "description": "How many days of history to return", + "schema": { + "type": "integer", + "minimum": 0, + "maximum": 365, + "default": 30 + } + } + ], + "responses": { + "200": { + "description": "The storm dashboard of a player.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/StormDashboardJson" + } + } + } + } + } + } + }, + "/api/racer": { + "post": { + "operationId": "racerPost", + "summary": "Create and join a puzzle race", + "description": "Create a new private [puzzle race](https://lichess.org/racer).\nThe Lichess user who creates the race must join the race page,\nand manually start the race when enough players have joined.\n\n- \n", + "tags": [ + "Puzzles" + ], + "security": [ + { + "OAuth2": [ + "racer:write" + ] + } + ], + "responses": { + "200": { + "description": "The new puzzle race.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PuzzleRaceJson" + } + } + } + } + } + } + }, + "/api/users": { + "post": { + "operationId": "apiUsers", + "summary": "Get users by ID", + "tags": [ + "Users" + ], + "security": [], + "description": "Get up to 300 users by their IDs. Users are returned in the same order as the IDs.\n\nThe method is `POST` to allow a longer list of IDs to be sent in the request body.\n\nPlease do not try to download all the Lichess users with this endpoint, or any other endpoint.\nAn API is not a way to fully export a website. We do not provide a full download of the Lichess users.\n\nThis endpoint is limited to 8,000 users every 10 minutes, and 120,000 every day.\n", + "requestBody": { + "description": "User IDs separated by commas.", + "required": true, + "content": { + "text/plain": { + "schema": { + "type": "string" + }, + "example": "aliquantus,chess-network,lovlas" + } + } + }, + "responses": { + "200": { + "description": "The list of users.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/User" + } + } + } + } + } + } + } + }, + "/api/account": { + "get": { + "operationId": "accountMe", + "summary": "Get my profile", + "description": "Public information about the logged in user.\n", + "tags": [ + "Account" + ], + "security": [ + { + "OAuth2": [] + } + ], + "responses": { + "200": { + "description": "The public information about the logged in user.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UserExtended" + } + } + } + } + } + } + }, + "/api/account/email": { + "get": { + "operationId": "accountEmail", + "summary": "Get my email address", + "description": "Read the email address of the logged in user.\n", + "tags": [ + "Account" + ], + "security": [ + { + "OAuth2": [ + "email:read" + ] + } + ], + "responses": { + "200": { + "description": "The email address of the logged in user.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "properties": { + "email": { + "type": "string" + } + }, + "example": { + "email": "abathur@mail.org" + } + } + } + } + } + } + } + }, + "/api/account/preferences": { + "get": { + "operationId": "account", + "summary": "Get my preferences", + "description": "Read the preferences of the logged in user.\n\n- \n- \n", + "tags": [ + "Account" + ], + "security": [ + { + "OAuth2": [ + "preference:read" + ] + } + ], + "responses": { + "200": { + "description": "The preferences of the logged in user.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "properties": { + "prefs": { + "$ref": "#/components/schemas/UserPreferences" + }, + "language": { + "type": "string", + "example": "en-GB" + } + } + } + } + } + } + } + } + }, + "/api/account/kid": { + "get": { + "operationId": "accountKid", + "summary": "Get my kid mode status", + "description": "Read the kid mode status of the logged in user.\n\n- \n", + "tags": [ + "Account" + ], + "security": [ + { + "OAuth2": [ + "preference:read" + ] + } + ], + "responses": { + "200": { + "description": "The kid mode status of the logged in user.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "properties": { + "kid": { + "type": "boolean" + } + }, + "example": { + "kid": false + } + } + } + } + } + } + }, + "post": { + "operationId": "accountKidPost", + "summary": "Set my kid mode status", + "description": "Set the kid mode status of the logged in user.\n\n- \n", + "tags": [ + "Account" + ], + "security": [ + { + "OAuth2": [ + "preference:write" + ] + } + ], + "parameters": [ + { + "in": "query", + "name": "v", + "required": true, + "description": "Kid mode status", + "schema": { + "type": "boolean" + }, + "example": true + } + ], + "responses": { + "200": { + "description": "The kid mode status was set successfully for the logged in user.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + } + } + } + }, + "/game/export/{gameId}": { + "get": { + "operationId": "gamePgn", + "summary": "Export one game", + "description": "Download one game in either PGN or JSON format.\n\nOngoing games have their last 3 moves omitted, after move 5.\n", + "tags": [ + "Games" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "gameId", + "description": "The game ID (8 characters).", + "required": true, + "schema": { + "type": "string" + } + }, + { + "in": "query", + "name": "moves", + "description": "Include the PGN moves.", + "schema": { + "type": "boolean", + "default": true + } + }, + { + "in": "query", + "name": "pgnInJson", + "description": "Include the full PGN within the JSON response, in a `pgn` field.", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "tags", + "description": "Include the PGN tags.", + "schema": { + "type": "boolean", + "default": true + } + }, + { + "in": "query", + "name": "clocks", + "description": "Include clock status when available.\n\nEither as PGN comments: `2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] }`\n\nOr in a `clocks` JSON field, as centisecond integers, depending on the response type.\n", + "schema": { + "type": "boolean", + "default": true + } + }, + { + "in": "query", + "name": "evals", + "description": "Include analysis evaluations and comments, when available.\n\nEither as PGN comments: `12. Bxf6 { [%eval 0.23] } a3 { [%eval -1.09] }`\n\nOr in an `analysis` JSON field, depending on the response type.\n", + "schema": { + "type": "boolean", + "default": true + } + }, + { + "in": "query", + "name": "accuracy", + "description": "Include [accuracy percent](https://lichess.org/page/accuracy) of each player, when available.\n", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "opening", + "description": "Include the opening name.\n\nExample: `[Opening \"King's Gambit Accepted, King's Knight Gambit\"]`\n", + "schema": { + "type": "boolean", + "default": true + } + }, + { + "in": "query", + "name": "literate", + "description": "Insert textual annotations in the PGN about the opening, analysis variations, mistakes, and game termination.\n\nExample: `5... g4? { (-0.98 → 0.60) Mistake. Best move was h6. } (5... h6 6. d4 Ne7 7. g3 d5 8. exd5 fxg3 9. hxg3 c6 10. dxc6)`\n", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "players", + "description": "URL of a text file containing real names and ratings, to replace Lichess usernames and ratings in the PGN.\nExample: \n", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The game representation.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/x-chess-pgn": { + "schema": { + "$ref": "#/components/schemas/GamePgn" + } + }, + "application/json": { + "schema": { + "$ref": "#/components/schemas/GameJson" + } + } + } + } + } + } + }, + "/api/user/{username}/current-game": { + "get": { + "operationId": "apiUserCurrentGame", + "summary": "Export ongoing game of a user", + "description": "Download the ongoing game, or the last game played, of a user.\nAvailable in either PGN or JSON format.\nIf the game is ongoing, the 3 last moves are omitted.\n", + "tags": [ + "Games" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "username", + "required": true, + "schema": { + "type": "string" + } + }, + { + "in": "query", + "name": "moves", + "description": "Include the PGN moves.", + "schema": { + "type": "boolean", + "default": true + } + }, + { + "in": "query", + "name": "pgnInJson", + "description": "Include the full PGN within the JSON response, in a `pgn` field.", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "tags", + "description": "Include the PGN tags.", + "schema": { + "type": "boolean", + "default": true + } + }, + { + "in": "query", + "name": "clocks", + "description": "Include clock status when available.\n\nEither as PGN comments: `2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] }`\n\nOr in a `clocks` JSON field, as centisecond integers, depending on the response type.\n", + "schema": { + "type": "boolean", + "default": true + } + }, + { + "in": "query", + "name": "evals", + "description": "Include analysis evaluations and comments, when available.\n\nEither as PGN comments: `12. Bxf6 { [%eval 0.23] } a3 { [%eval -1.09] }`\n\nOr in an `analysis` JSON field, depending on the response type.\n", + "schema": { + "type": "boolean", + "default": true + } + }, + { + "in": "query", + "name": "accuracy", + "description": "Include [accuracy percent](https://lichess.org/page/accuracy) of each player, when available.\n", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "opening", + "description": "Include the opening name.\n\nExample: `[Opening \"King's Gambit Accepted, King's Knight Gambit\"]`\n", + "schema": { + "type": "boolean", + "default": true + } + }, + { + "in": "query", + "name": "literate", + "description": "Insert textual annotations in the PGN about the opening, analysis variations, mistakes, and game termination.\n\nExample: `5... g4? { (-0.98 → 0.60) Mistake. Best move was h6. } (5... h6 6. d4 Ne7 7. g3 d5 8. exd5 fxg3 9. hxg3 c6 10. dxc6)`\n", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "players", + "description": "URL of a text file containing real names and ratings, to replace Lichess usernames and ratings in the PGN.\nExample: \n", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The ongoing (or last) game of a user.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/x-chess-pgn": { + "schema": { + "$ref": "#/components/schemas/GamePgn" + } + }, + "application/json": { + "schema": { + "$ref": "#/components/schemas/GameJson" + } + } + } + } + } + } + }, + "/api/games/user/{username}": { + "get": { + "operationId": "apiGamesUser", + "summary": "Export games of a user", + "description": "Download all games of any user in PGN or [ndjson](#section/Introduction/Streaming-with-ND-JSON) format.\n\nGames are sorted by reverse chronological order (most recent first).\n\nWe recommend streaming the response, for it can be very long.\n for instance has more than 500,000 games.\n\nThe game stream is throttled, depending on who is making the request:\n - Anonymous request: 20 games per second\n - [OAuth2 authenticated](#section/Introduction/Authentication) request: 30 games per second\n - Authenticated, downloading your own games: 60 games per second\n", + "tags": [ + "Games" + ], + "security": [ + { + "OAuth2": [] + } + ], + "parameters": [ + { + "in": "path", + "name": "username", + "description": "The user name.", + "schema": { + "type": "string" + }, + "required": true + }, + { + "in": "query", + "name": "since", + "description": "Download games played since this timestamp. Defaults to account creation date.", + "schema": { + "type": "integer", + "minimum": 1356998400070 + } + }, + { + "in": "query", + "name": "until", + "description": "Download games played until this timestamp. Defaults to now.", + "schema": { + "type": "integer", + "minimum": 1356998400070 + } + }, + { + "in": "query", + "name": "max", + "description": "How many games to download. Leave empty to download all games.", + "schema": { + "type": "integer", + "minimum": 1 + } + }, + { + "in": "query", + "name": "vs", + "description": "[Filter] Only games played against this opponent", + "schema": { + "type": "string" + } + }, + { + "in": "query", + "name": "rated", + "description": "[Filter] Only rated (`true`) or casual (`false`) games", + "schema": { + "type": "boolean" + } + }, + { + "in": "query", + "name": "perfType", + "description": "[Filter] Only games in these speeds or variants.\n \nMultiple perf types can be specified, separated by a comma.\n \nExample: blitz,rapid,classical", + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/PerfType" + }, + { + "default": null + } + ] + } + }, + { + "in": "query", + "name": "color", + "description": "[Filter] Only games played as this color.", + "schema": { + "type": "string", + "enum": [ + "white", + "black" + ] + } + }, + { + "in": "query", + "name": "analysed", + "description": "[Filter] Only games with or without a computer analysis available", + "schema": { + "type": "boolean" + } + }, + { + "in": "query", + "name": "moves", + "description": "Include the PGN moves.", + "schema": { + "type": "boolean", + "default": true + } + }, + { + "in": "query", + "name": "pgnInJson", + "description": "Include the full PGN within the JSON response, in a `pgn` field.\nThe response type must be set to `application/x-ndjson` by the request `Accept` header.", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "tags", + "description": "Include the PGN tags.", + "schema": { + "type": "boolean", + "default": true + } + }, + { + "in": "query", + "name": "clocks", + "description": "Include clock status when available.\n\nEither as PGN comments: `2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] }`\n\nOr in a `clocks` JSON field, as centisecond integers, depending on the response type.\n", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "evals", + "description": "Include analysis evaluations and comments, when available.\n\nEither as PGN comments: `12. Bxf6 { [%eval 0.23] } a3 { [%eval -1.09] }`\n\nOr in an `analysis` JSON field, depending on the response type.\n", + "schema": { + "type": "boolean", + "default": true + } + }, + { + "in": "query", + "name": "accuracy", + "description": "Include [accuracy percent](https://lichess.org/page/accuracy) of each player, when available.\n", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "opening", + "description": "Include the opening name.\n\nExample: `[Opening \"King's Gambit Accepted, King's Knight Gambit\"]`\n", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "ongoing", + "description": "Include ongoing games. The last 3 moves will be omitted.", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "finished", + "description": "Include finished games. Set to `false` to only get ongoing games.", + "schema": { + "type": "boolean", + "default": true + } + }, + { + "in": "query", + "name": "literate", + "description": "Insert textual annotations in the PGN about the opening, analysis variations, mistakes, and game termination.\n\nExample: `5... g4? { (-0.98 → 0.60) Mistake. Best move was h6. } (5... h6 6. d4 Ne7 7. g3 d5 8. exd5 fxg3 9. hxg3 c6 10. dxc6)`\n", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "lastFen", + "description": "Include the FEN notation of the last position of the game.\n", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "players", + "description": "URL of a text file containing real names and ratings, to replace Lichess usernames and ratings in the PGN.\nExample: \n", + "schema": { + "type": "string" + } + }, + { + "in": "query", + "name": "sort", + "description": "Sort order of the games.", + "schema": { + "type": "string", + "default": "dateDesc", + "enum": [ + "dateAsc", + "dateDesc" + ] + } + } + ], + "responses": { + "200": { + "description": "The games of the user.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/x-chess-pgn": { + "schema": { + "$ref": "#/components/schemas/GamePgn" + } + }, + "application/x-ndjson": { + "schema": { + "$ref": "#/components/schemas/GameJson" + } + } + } + } + } + } + }, + "/api/games/export/_ids": { + "post": { + "operationId": "gamesExportIds", + "summary": "Export games by IDs", + "description": "Download games by IDs in PGN or [ndjson](#section/Introduction/Streaming-with-ND-JSON) format, depending on the request Accept header.\n\nGames are sorted by reverse chronological order (most recent first)\n\nThe method is `POST` so a longer list of IDs can be sent in the request body.\n\n300 IDs can be submitted.\n\nOngoing games have their last 3 moves omitted, after move 5.\n", + "tags": [ + "Games" + ], + "security": [], + "requestBody": { + "description": "Game IDs separated by commas. Up to 300.", + "required": true, + "content": { + "text/plain": { + "schema": { + "type": "string" + }, + "example": "TJxUmbWK,4OtIh2oh,ILwozzRZ" + } + } + }, + "parameters": [ + { + "in": "query", + "name": "moves", + "description": "Include the PGN moves.", + "schema": { + "type": "boolean", + "default": true + } + }, + { + "in": "query", + "name": "pgnInJson", + "description": "Include the full PGN within the JSON response, in a `pgn` field.", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "tags", + "description": "Include the PGN tags.", + "schema": { + "type": "boolean", + "default": true + } + }, + { + "in": "query", + "name": "clocks", + "description": "Include clock status when available.\n\nEither as PGN comments: `2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] }`\n\nOr in a `clocks` JSON field, as centisecond integers, depending on the response type.\n", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "evals", + "description": "Include analysis evaluations and comments, when available.\n\nEither as PGN comments: `12. Bxf6 { [%eval 0.23] } a3 { [%eval -1.09] }`\n\nOr in an `analysis` JSON field, depending on the response type.\n", + "schema": { + "type": "boolean", + "default": true + } + }, + { + "in": "query", + "name": "accuracy", + "description": "Include [accuracy percent](https://lichess.org/page/accuracy) of each player, when available.\n", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "opening", + "description": "Include the opening name.\n\nExample: `[Opening \"King's Gambit Accepted, King's Knight Gambit\"]`\n", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "literate", + "description": "Insert textual annotations in the PGN about the opening, analysis variations, mistakes, and game termination.\n\nExample: `5... g4? { (-0.98 → 0.60) Mistake. Best move was h6. } (5... h6 6. d4 Ne7 7. g3 d5 8. exd5 fxg3 9. hxg3 c6 10. dxc6)`\n", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "players", + "description": "URL of a text file containing real names and ratings, to replace Lichess usernames and ratings in the PGN.\nExample: \n", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The representation of the games.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/x-chess-pgn": { + "schema": { + "$ref": "#/components/schemas/GamePgn" + } + }, + "application/x-ndjson": { + "schema": { + "$ref": "#/components/schemas/GameJson" + } + } + } + } + } + } + }, + "/api/stream/games-by-users": { + "post": { + "operationId": "gamesByUsers", + "summary": "Stream games of users", + "description": "Stream the games played between a list of users, in real time.\nOnly games where **both players** are part of the list are included.\n\nThe stream emits an event each time a game is started or finished.\n\nTo also get all current ongoing games at the beginning of the stream, use the `withCurrentGames` flag.\n\nGames are streamed as [ndjson](#section/Introduction/Streaming-with-ND-JSON).\n\nMaximum number of users: 300.\n\nThe method is `POST` so a longer list of IDs can be sent in the request body.\n", + "tags": [ + "Games" + ], + "security": [], + "requestBody": { + "description": "Up to 300 user IDs separated by commas.\nExample: `aliquantus,chess-network,lovlas`\n", + "required": true, + "content": { + "text/plain": { + "schema": { + "type": "string" + } + } + } + }, + "parameters": [ + { + "in": "query", + "name": "withCurrentGames", + "description": "Include the already started games at the beginning of the stream.", + "schema": { + "type": "boolean", + "default": false + } + } + ], + "responses": { + "200": { + "description": "The stream of the games played between the users.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/x-ndjson": { + "schema": { + "$ref": "#/components/schemas/GameStream" + } + } + } + } + } + } + }, + "/api/stream/games/{streamId}": { + "post": { + "operationId": "gamesByIds", + "summary": "Stream games by IDs", + "description": "Creates a stream of games from an arbitrary streamId, and a list of game IDs.\n\nThe stream first outputs the games that already exists, then emits an event each time a game is started or finished.\n\nGames are streamed as [ndjson](#section/Introduction/Streaming-with-ND-JSON).\n\nMaximum number of games: 500 for anonymous requests, or 1000 for [OAuth2 authenticated](#section/Introduction/Authentication) requests.\n\nWhile the stream is open, it is possible to [add new game IDs to watch](#operation/gamesByIdsAdd).\n", + "tags": [ + "Games" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "streamId", + "schema": { + "type": "string", + "description": "Arbitrary stream ID that you can later use to add game IDs to the stream.", + "example": "myAppName-someRandomId" + }, + "required": true + } + ], + "requestBody": { + "description": "Up to 500 or 1000 game IDs separated by commas.\nExample: `gameId01,gameId02,gameId03`\n", + "required": true, + "content": { + "text/plain": { + "schema": { + "type": "string" + } + } + } + }, + "responses": { + "200": { + "description": "The stream of the games matching the requested IDs.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/x-ndjson": { + "schema": { + "$ref": "#/components/schemas/GameStream" + } + } + } + } + } + } + }, + "/api/stream/games/{streamId}/add": { + "post": { + "operationId": "gamesByIdsAdd", + "summary": "Add game IDs to stream", + "description": "Add new game IDs for [an existing stream](#operation/gamesByIds) to watch.\nThe stream will immediately outputs the games that already exists, then emit an event each time a game is started or finished.\n", + "tags": [ + "Games" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "streamId", + "schema": { + "type": "string", + "description": "The stream ID you used to [create the stream](#operation/gamesByIds).", + "example": "myAppName-someRandomId" + }, + "required": true + } + ], + "requestBody": { + "description": "Up to 500 or 1000 game IDs separated by commas.\nExample: `gameId04,gameId05,gameId06`\n", + "required": true, + "content": { + "text/plain": { + "schema": { + "type": "string" + } + } + } + }, + "responses": { + "200": { + "description": "The game IDs have been added to the stream.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + } + } + } + }, + "/api/account/playing": { + "get": { + "operationId": "apiAccountPlaying", + "summary": "Get my ongoing games", + "description": "Get the ongoing games of the current user.\nReal-time and correspondence games are included.\nThe most urgent games are listed first.\n", + "tags": [ + "Games" + ], + "security": [ + { + "OAuth2": [] + } + ], + "parameters": [ + { + "in": "query", + "name": "nb", + "description": "Max number of games to fetch", + "schema": { + "type": "integer", + "default": 9, + "minimum": 1, + "maximum": 50 + } + } + ], + "responses": { + "200": { + "description": "The ongoing games of the logged in user.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "example": { + "nowPlaying": [ + { + "gameId": "rCRw1AuO", + "fullId": "rCRw1AuOvonq", + "color": "black", + "fen": "r1bqkbnr/pppp2pp/2n1pp2/8/8/3PP3/PPPB1PPP/RN1QKBNR w KQkq - 2 4", + "hasMoved": true, + "isMyTurn": false, + "lastMove": "b8c6", + "opponent": { + "id": "philippe", + "rating": 1790, + "username": "Philippe" + }, + "perf": "correspondence", + "rated": false, + "secondsLeft": 1209600, + "source": "friend", + "speed": "correspondence", + "variant": { + "key": "standard", + "name": "Standard" + } + } + ] + } + } + } + } + } + } + } + }, + "/api/stream/game/{id}": { + "get": { + "operationId": "streamGame", + "summary": "Stream moves of a game", + "description": "Stream positions and moves of any ongoing game, in [ndjson](#section/Introduction/Streaming-with-ND-JSON).\n\nA description of the game is sent as a first message.\nThen a message is sent each time a move is played.\nFinally a description of the game is sent when it finishes, and the stream is closed.\n\nAfter move 5, the stream intentionally remains 3 moves behind the game status, as to prevent cheat bots from using this API.\n\nNo more than 8 game streams can be opened at the same time from the same IP address.\n", + "tags": [ + "Games" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "id", + "schema": { + "type": "string", + "example": "LuGQwhBb" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The stream of the game moves.", + "content": { + "application/x-ndjson": { + "schema": { + "$ref": "#/components/schemas/MoveStream" + } + } + } + } + } + } + }, + "/api/import": { + "post": { + "operationId": "gameImport", + "summary": "Import one game", + "description": "Import a game from PGN. See .\n\nRate limiting: 200 games per hour for OAuth requests, 100 games per hour for anonymous requests.\n\nTo broadcast ongoing games, consider [pushing to a broadcast instead](#operation/broadcastPush).\n", + "tags": [ + "Games" + ], + "security": [ + { + "OAuth2": [] + } + ], + "requestBody": { + "description": "A single game to import", + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "pgn": { + "type": "string", + "description": "The PGN. It can contain only one game. Most standard tags are supported." + } + } + } + } + } + }, + "responses": { + "200": { + "description": "The game was successfully imported.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "example": { + "id": "R6iLjwz5", + "url": "https://lichess.org/R6iLjwz5" + } + } + } + } + } + } + } + }, + "/api/tv/channels": { + "get": { + "operationId": "tvChannels", + "summary": "Get current TV games", + "description": "Get basic info about the best games being played for each speed and variant,\nbut also computer games and bot games.\n\nSee [lichess.org/tv](https://lichess.org/tv).\n", + "tags": [ + "TV" + ], + "security": [], + "responses": { + "200": { + "description": "The list of games being played for each speed and variant.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "example": { + "Bot": { + "user": { + "id": "leelachess", + "name": "LeelaChess", + "title": "BOT" + }, + "rating": 2660, + "gameId": "Zznv9MIl" + }, + "Blitz": { + "user": { + "id": "lekkerkortook", + "name": "LekkerKortOok" + }, + "rating": 2603, + "gameId": "hTJ4v7Mp" + }, + "Racing Kings": { + "user": { + "id": "chesslo21", + "name": "chesslo21" + }, + "rating": 2123, + "gameId": "lgCDl5Of" + }, + "UltraBullet": { + "user": { + "id": "farmville", + "name": "Farmville" + }, + "rating": 2338, + "gameId": "NEY6OQ32" + }, + "Bullet": { + "user": { + "id": "nurmibrah", + "name": "nurmiBrah" + }, + "rating": 2499, + "gameId": "5LgyE516" + }, + "Classical": { + "user": { + "id": "holden_m_j_thomas", + "name": "Holden_M_J_Thomas" + }, + "rating": 1806, + "gameId": "k3oLby6N" + }, + "Three-check": { + "user": { + "id": "pepellou", + "name": "pepellou", + "patron": true + }, + "rating": 1978, + "gameId": "Og5RCvmu" + }, + "Antichess": { + "user": { + "id": "maria-bakkar", + "name": "maria-bakkar" + }, + "rating": 2103, + "gameId": "toCr41yx" + }, + "Computer": { + "user": { + "id": "oh_my_goat_im_so_bat", + "name": "oh_my_goat_Im_so_bat" + }, + "rating": 2314, + "gameId": "TkI4qZxu" + }, + "Horde": { + "user": { + "id": "habitualchess", + "name": "HabitualChess" + }, + "rating": 1803, + "gameId": "oMofN63H" + }, + "Rapid": { + "user": { + "id": "denpayd", + "name": "DenpaYD" + }, + "rating": 2289, + "gameId": "IcWOl8ee" + }, + "Atomic": { + "user": { + "id": "meetyourdemise", + "name": "MeetYourDemise" + }, + "rating": 2210, + "gameId": "tvMxtCMN" + }, + "Crazyhouse": { + "user": { + "id": "mathace", + "name": "mathace" + }, + "rating": 2397, + "gameId": "i3gTZlUb" + }, + "Chess960": { + "user": { + "id": "voja_7", + "name": "voja_7" + }, + "rating": 1782, + "gameId": "lrXLcedu" + }, + "King of the Hill": { + "user": { + "id": "nadime", + "name": "Nadime" + }, + "rating": 1500, + "gameId": "DsQn8aEV" + }, + "Top Rated": { + "user": { + "id": "lekkerkortook", + "name": "LekkerKortOok" + }, + "rating": 2603, + "gameId": "hTJ4v7Mp" + } + } + } + } + } + } + } + } + }, + "/api/tv/feed": { + "get": { + "operationId": "tvFeed", + "summary": "Stream current TV game", + "description": "Stream positions and moves of the current [TV game](https://lichess.org/tv) in [ndjson](#section/Introduction/Streaming-with-ND-JSON).\nA summary of the game is sent as a first message, and when the featured game changes.\n\nTry it with `curl https://lichess.org/api/tv/feed`.\n", + "tags": [ + "TV" + ], + "security": [], + "responses": { + "200": { + "description": "The stream of the current TV game.", + "content": { + "application/x-ndjson": { + "schema": { + "example": { + "t": "featured", + "d": { + "id": "qVSOPtMc", + "orientation": "black", + "players": [ + { + "color": "white", + "user": { + "name": "lizen9", + "id": "lizen9", + "title": "GM" + }, + "rating": 2531 + }, + { + "color": "black", + "user": { + "name": "lizen29", + "title": "WGM", + "id": "lizen29" + }, + "rating": 2594 + } + ], + "fen": "rnbqk1r1/ppp1ppbp/8/N2p2p1/8/1PQPP3/P1P2PPn/R1B1K1NR" + } + } + } + } + } + } + } + } + }, + "/api/tv/{channel}": { + "get": { + "operationId": "tvChannelGames", + "summary": "Get best ongoing games of a TV channel", + "description": "Get a list of ongoing games for a given TV channel. Similar to [lichess.org/games](https://lichess.org/games).\n\nAvailable in PGN or [ndjson](#section/Introduction/Streaming-with-ND-JSON) format, depending on the request Accept header.\n", + "tags": [ + "TV" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "channel", + "description": "The name of the channel in camel case.", + "schema": { + "type": "string" + }, + "required": true + }, + { + "in": "query", + "name": "nb", + "description": "Number of games to fetch.", + "schema": { + "type": "number", + "default": 10, + "minimum": 1, + "maximum": 30 + } + }, + { + "in": "query", + "name": "moves", + "description": "Include the PGN moves.", + "schema": { + "type": "boolean", + "default": true + } + }, + { + "in": "query", + "name": "pgnInJson", + "description": "Include the full PGN within the JSON response, in a `pgn` field.", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "tags", + "description": "Include the PGN tags.", + "schema": { + "type": "boolean", + "default": true + } + }, + { + "in": "query", + "name": "clocks", + "description": "Include clock status when available.\n\nEither as PGN comments: `2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] }`\n\nOr in a `clocks` JSON field, as centisecond integers, depending on the response type.\n", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "opening", + "description": "Include the opening name.\n\nExample: `[Opening \"King's Gambit Accepted, King's Knight Gambit\"]`\n", + "schema": { + "type": "boolean", + "default": false + } + } + ], + "responses": { + "200": { + "description": "The representation of the games.", + "content": { + "application/x-chess-pgn": { + "schema": { + "$ref": "#/components/schemas/GamePgn" + } + }, + "application/x-ndjson": { + "schema": { + "$ref": "#/components/schemas/GameJson" + } + } + } + } + } + } + }, + "/api/tournament": { + "get": { + "operationId": "apiTournament", + "summary": "Get current tournaments", + "description": "Get recently finished, ongoing, and upcoming tournaments.\n\nThis API is used to display the [Lichess tournament schedule](https://lichess.org/tournament).\n", + "tags": [ + "Arena tournaments" + ], + "security": [], + "responses": { + "200": { + "description": "The list of current tournaments.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ArenaTournaments" + } + } + } + } + } + }, + "post": { + "operationId": "apiTournamentPost", + "summary": "Create a new Arena tournament", + "description": "Create a public or private Arena tournament.\n\nThis endpoint mirrors the form on .\n\nYou can create up to 12 public tournaments per day, or 24 private tournaments.\n\nA team battle can be created by specifying the `teambBattleByTeam` argument.\n\nAdditional restrictions:\n - clockTime + clockIncrement > 0\n - 15s and 0+1 variant tournaments cannot be rated\n - Clock time in comparison to tournament length must be reasonable: 3 <= (minutes * 60) / (96 * clockTime + 48 * clockIncrement + 15) <= 150\n", + "tags": [ + "Arena tournaments" + ], + "security": [ + { + "OAuth2": [ + "tournament:write" + ] + } + ], + "requestBody": { + "description": "Parameters of the tournament", + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The tournament name. Leave empty to get a random Grandmaster name", + "minLength": 2, + "maxLength": 30 + }, + "clockTime": { + "type": "number", + "description": "Clock initial time in minutes", + "example": 2, + "enum": [ + 0, + 0.25, + 0.5, + 0.75, + 1, + 1.5, + 2, + 3, + 4, + 5, + 6, + 7, + 8, + 10, + 15, + 20, + 25, + 30, + 40, + 50, + 60 + ] + }, + "clockIncrement": { + "type": "integer", + "description": "Clock increment in seconds", + "example": 1, + "enum": [ + 0, + 1, + 2, + 3, + 4, + 5, + 6, + 7, + 10, + 15, + 20, + 25, + 30, + 40, + 50, + 60 + ] + }, + "minutes": { + "type": "integer", + "description": "How long the tournament lasts, in minutes", + "example": 60, + "enum": [ + 20, + 25, + 30, + 35, + 40, + 45, + 50, + 55, + 60, + 70, + 80, + 90, + 100, + 110, + 120, + 150, + 180, + 210, + 240, + 270, + 300, + 330, + 360, + 420, + 480, + 540, + 600, + 720 + ] + }, + "waitMinutes": { + "type": "integer", + "description": "How long to wait before starting the tournament, from now, in minutes", + "default": 5, + "enum": [ + 1, + 2, + 3, + 5, + 10, + 15, + 20, + 30, + 45, + 60 + ] + }, + "startDate": { + "type": "integer", + "description": "Timestamp (in milliseconds) to start the tournament at a given date and time. Overrides the `waitMinutes` setting" + }, + "variant": { + "$ref": "#/components/schemas/VariantKey" + }, + "rated": { + "type": "boolean", + "description": "Games are rated and impact players ratings", + "default": true + }, + "position": { + "$ref": "#/components/schemas/FromPositionFEN" + }, + "berserkable": { + "type": "boolean", + "description": "Whether the players can use berserk. Only allowed if clockIncrement <= clockTime * 2", + "default": true + }, + "streakable": { + "type": "boolean", + "description": "After 2 wins, consecutive wins grant 4 points instead of 2.", + "default": true + }, + "hasChat": { + "type": "boolean", + "description": "Whether the players can discuss in a chat", + "default": true + }, + "description": { + "type": "string", + "description": "Anything you want to tell players about the tournament" + }, + "password": { + "type": "string", + "description": "Make the tournament private, and restrict access with a password.\nYou can also [generate user-specific entry codes](https://github.com/lichess-org/api/tree/master/example/tournament-entry-code)\nbased on this password.\n" + }, + "teamBattleByTeam": { + "type": "string", + "description": "Set the ID of a team you lead to create a team battle.\nThe other teams can be added using the [team battle edit endpoint](#operation/apiTournamentTeamBattlePost).\n" + }, + "conditions.teamMember.teamId": { + "type": "string", + "description": "Restrict entry to members of a team.\n\nThe teamId is the last part of a team URL, e.g. `https://lichess.org/team/coders` has teamId = `coders`.\n\nLeave empty to let everyone join the tournament.\n\nDo not use this to create team battles, use `teamBattleByTeam` instead.\n" + }, + "conditions.minRating.rating": { + "type": "integer", + "description": "Minimum rating to join. Leave empty to let everyone join the tournament.", + "enum": [ + 1000, + 1100, + 1200, + 1300, + 1400, + 1500, + 1600, + 1700, + 1800, + 1900, + 2000, + 2100, + 2200, + 2300, + 2400, + 2500, + 2600 + ] + }, + "conditions.maxRating.rating": { + "type": "integer", + "description": "Maximum rating to join. Based on best rating reached in the last 7 days. Leave empty to let everyone join the tournament.", + "enum": [ + 2200, + 2100, + 2000, + 1900, + 1800, + 1700, + 1600, + 1500, + 1400, + 1300, + 1200, + 1100, + 1000, + 900, + 800 + ] + }, + "conditions.nbRatedGame.nb": { + "type": "integer", + "description": "Minimum number of rated games required to join.", + "enum": [ + 0, + 5, + 10, + 15, + 20, + 30, + 40, + 50, + 75, + 100, + 150, + 200 + ] + }, + "conditions.allowList": { + "type": "string", + "description": "Predefined list of usernames that are allowed to join, separated by commas.\nIf this list is non-empty, then usernames absent from this list will be forbidden to join.\nAdding `%titled` to the list additionally allows any titled player to join.\nExample: `thibault,german11,%titled`\n" + } + }, + "required": [ + "clockTime", + "clockIncrement", + "minutes" + ] + } + } + } + }, + "responses": { + "200": { + "description": "The Arena tournament has been successfully created.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ArenaTournament" + } + } + } + }, + "400": { + "description": "The creation of the Arena tournament failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/tournament/{id}": { + "parameters": [ + { + "in": "path", + "name": "id", + "description": "The tournament ID.", + "schema": { + "type": "string" + }, + "required": true + } + ], + "get": { + "operationId": "tournament", + "summary": "Get info about an Arena tournament", + "description": "Get detailed info about recently finished, current, or upcoming tournament's duels, player standings, and other info.\n", + "tags": [ + "Arena tournaments" + ], + "security": [], + "parameters": [ + { + "in": "query", + "name": "page", + "description": "Specify which page of player standings to view.", + "schema": { + "type": "number", + "example": 1, + "default": 1, + "minimum": 1, + "maximum": 200 + } + } + ], + "responses": { + "200": { + "description": "The information of the Arena tournament.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ArenaTournamentVariantIsKey" + } + } + } + } + } + }, + "post": { + "operationId": "apiTournamentUpdate", + "summary": "Update an Arena tournament", + "description": "Update an Arena tournament.\n\nBe mindful not to make important changes to ongoing tournaments.\n\nCan be used to update a team battle.\n\nAdditional restrictions:\n - clockTime + clockIncrement > 0\n - 15s and 0+1 variant tournaments cannot be rated\n - Clock time in comparison to tournament length must be reasonable: 3 <= (minutes * 60) / (96 * clockTime + 48 * clockIncrement + 15) <= 150\n", + "tags": [ + "Arena tournaments" + ], + "security": [ + { + "OAuth2": [ + "tournament:write" + ] + } + ], + "requestBody": { + "description": "Parameters of the tournament", + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The tournament name. Leave empty to get a random Grandmaster name", + "minLength": 2, + "maxLength": 30 + }, + "clockTime": { + "type": "number", + "description": "Clock initial time in minutes", + "example": 2, + "enum": [ + 0, + 0.25, + 0.5, + 0.75, + 1, + 1.5, + 2, + 3, + 4, + 5, + 6, + 7, + 8, + 10, + 15, + 20, + 25, + 30, + 40, + 50, + 60 + ] + }, + "clockIncrement": { + "type": "integer", + "description": "Clock increment in seconds", + "example": 1, + "enum": [ + 0, + 1, + 2, + 3, + 4, + 5, + 6, + 7, + 10, + 15, + 20, + 25, + 30, + 40, + 50, + 60 + ] + }, + "minutes": { + "type": "integer", + "description": "How long the tournament lasts, in minutes", + "example": 60, + "enum": [ + 20, + 25, + 30, + 35, + 40, + 45, + 50, + 55, + 60, + 70, + 80, + 90, + 100, + 110, + 120, + 150, + 180, + 210, + 240, + 270, + 300, + 330, + 360, + 420, + 480, + 540, + 600, + 720 + ] + }, + "waitMinutes": { + "type": "integer", + "description": "How long to wait before starting the tournament, from now, in minutes", + "default": 5, + "enum": [ + 1, + 2, + 3, + 5, + 10, + 15, + 20, + 30, + 45, + 60 + ] + }, + "startDate": { + "type": "integer", + "description": "Timestamp (in milliseconds) to start the tournament at a given date and time. Overrides the `waitMinutes` setting" + }, + "variant": { + "$ref": "#/components/schemas/VariantKey" + }, + "rated": { + "type": "boolean", + "description": "Games are rated and impact players ratings", + "default": true + }, + "position": { + "$ref": "#/components/schemas/FromPositionFEN" + }, + "berserkable": { + "type": "boolean", + "description": "Whether the players can use berserk. Only allowed if clockIncrement <= clockTime * 2", + "default": true + }, + "streakable": { + "type": "boolean", + "description": "After 2 wins, consecutive wins grant 4 points instead of 2.", + "default": true + }, + "hasChat": { + "type": "boolean", + "description": "Whether the players can discuss in a chat", + "default": true + }, + "description": { + "type": "string", + "description": "Anything you want to tell players about the tournament" + }, + "password": { + "type": "string", + "description": "Make the tournament private, and restrict access with a password" + }, + "conditions.minRating.rating": { + "type": "integer", + "description": "Minimum rating to join. Leave empty to let everyone join the tournament.", + "enum": [ + 1000, + 1100, + 1200, + 1300, + 1400, + 1500, + 1600, + 1700, + 1800, + 1900, + 2000, + 2100, + 2200, + 2300, + 2400, + 2500, + 2600 + ] + }, + "conditions.maxRating.rating": { + "type": "integer", + "description": "Maximum rating to join. Based on best rating reached in the last 7 days. Leave empty to let everyone join the tournament.", + "enum": [ + 2200, + 2100, + 2000, + 1900, + 1800, + 1700, + 1600, + 1500, + 1400, + 1300, + 1200, + 1100, + 1000, + 900, + 800 + ] + }, + "conditions.nbRatedGame.nb": { + "type": "integer", + "description": "Minimum number of rated games required to join.", + "enum": [ + 0, + 5, + 10, + 15, + 20, + 30, + 40, + 50, + 75, + 100, + 150, + 200 + ] + }, + "conditions.allowList": { + "type": "string", + "description": "Predefined list of usernames that are allowed to join, separated by commas.\nIf this list is non-empty, then usernames absent from this list will be forbidden to join.\nAdding `%titled` to the list additionally allows any titled player to join.\nExample: `thibault,german11,%titled`\n" + } + }, + "required": [ + "clockTime", + "clockIncrement", + "minutes" + ] + } + } + } + }, + "responses": { + "200": { + "description": "The Arena tournament was successfully updated.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ArenaTournament" + } + } + } + }, + "400": { + "description": "The update of the Arena tournament failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/tournament/{id}/join": { + "post": { + "operationId": "apiTournamentJoin", + "summary": "Join an Arena tournament", + "description": "Join an Arena tournament, possibly with a password and/or a team.\nAlso unpauses if you had previously [paused](#operation/apiTournamentWithdraw) the tournament.\n", + "tags": [ + "Arena tournaments" + ], + "security": [ + { + "OAuth2": [ + "tournament:write" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "id", + "description": "The tournament ID.", + "schema": { + "type": "string", + "example": "hL7vMrFQ" + }, + "required": true + } + ], + "requestBody": { + "description": "You may need these depending on the tournament to join", + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "password": { + "type": "string", + "description": "The tournament password, if one is required.\nCan also be a [user-specific entry code](https://github.com/lichess-org/api/tree/master/example/tournament-entry-code)\ngenerated and shared by the organizer.\n" + }, + "team": { + "type": "string", + "description": "The team to join the tournament with, for team battle tournaments" + }, + "pairMeAsap": { + "type": "boolean", + "default": false, + "description": "If the tournament is started, attempt to pair the user,\neven if they are not connected to the tournament page.\nThis expires after one minute, to avoid pairing a user who is long gone.\nYou may call \"join\" again to extend the waiting.\n" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "The tournament was successfully joined.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "400": { + "description": "Joining the tournament failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/tournament/{id}/withdraw": { + "post": { + "operationId": "apiTournamentWithdraw", + "summary": "Pause or leave an Arena tournament", + "description": "Leave a future Arena tournament, or take a break on an ongoing Arena tournament.\nIt's possible to join again later. Points and streaks are preserved.\n", + "tags": [ + "Arena tournaments" + ], + "security": [ + { + "OAuth2": [ + "tournament:write" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "id", + "description": "The tournament ID.", + "schema": { + "type": "string", + "example": "hL7vMrFQ" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The tournament was successfully paused or left.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "400": { + "description": "Pausing/leaving the tournament failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/tournament/{id}/terminate": { + "post": { + "operationId": "apiTournamentTerminate", + "summary": "Terminate an Arena tournament", + "description": "Terminate an Arena tournament\n", + "tags": [ + "Arena tournaments" + ], + "security": [ + { + "OAuth2": [ + "tournament:write" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "id", + "description": "The tournament ID.", + "schema": { + "type": "string", + "example": "hL7vMrFQ" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The tournament was successfully terminated.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "400": { + "description": "Terminating the tournament failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/tournament/team-battle/{id}": { + "post": { + "operationId": "apiTournamentTeamBattlePost", + "summary": "Update a team battle", + "description": "Set the teams and number of leaders of a team battle.\n\nTo update the other attributes of a team battle, use the [tournament update endpoint](#operation/apiTournamentUpdate).\n", + "tags": [ + "Arena tournaments" + ], + "security": [ + { + "OAuth2": [ + "tournament:write" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "id", + "description": "The tournament ID (8 characters)..", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "teams": { + "type": "string", + "description": "All team IDs of the team battle, separated by commas.\nMake sure to always send the full list.\nTeams that are not in the list will be removed from the team battle.\n\nExample: `coders,zhigalko_sergei-fan-club,hhSwTKZv`\n" + }, + "nbLeaders": { + "type": "integer", + "description": "Number team leaders per team." + } + }, + "required": [ + "teams", + "nbLeaders" + ] + } + } + } + }, + "responses": { + "200": { + "description": "The team battle tournament was successfully updated.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ArenaTournament" + } + } + } + }, + "400": { + "description": "The update of the team battle tournament failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/tournament/{id}/games": { + "get": { + "operationId": "gamesByTournament", + "summary": "Export games of an Arena tournament", + "description": "Download games of a tournament in PGN or [ndjson](#section/Introduction/Streaming-with-ND-JSON) format.\n\nGames are sorted by reverse chronological order (most recent first).\n\nThe game stream is throttled, depending on who is making the request:\n - Anonymous request: 20 games per second\n - [OAuth2 authenticated](#section/Introduction/Authentication) request: 30 games per second\n", + "tags": [ + "Arena tournaments" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "id", + "description": "The tournament ID.", + "schema": { + "type": "string" + }, + "required": true + }, + { + "in": "query", + "name": "player", + "description": "Only games of a particular player. Leave empty to fetch games of all players.", + "schema": { + "type": "string" + } + }, + { + "in": "query", + "name": "moves", + "description": "Include the PGN moves.", + "schema": { + "type": "boolean", + "default": true + } + }, + { + "in": "query", + "name": "pgnInJson", + "description": "Include the full PGN within the JSON response, in a `pgn` field.", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "tags", + "description": "Include the PGN tags.", + "schema": { + "type": "boolean", + "default": true + } + }, + { + "in": "query", + "name": "clocks", + "description": "Include clock status when available.\n\nEither as PGN comments: `2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] }`\n\nOr in a `clocks` JSON field, as centisecond integers, depending on the response type.\n", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "evals", + "description": "Include analysis evaluations and comments, when available.\n\nEither as PGN comments: `12. Bxf6 { [%eval 0.23] } a3 { [%eval -1.09] }`\n\nOr in an `analysis` JSON field, depending on the response type.\n", + "schema": { + "type": "boolean", + "default": true + } + }, + { + "in": "query", + "name": "accuracy", + "description": "Include [accuracy percent](https://lichess.org/page/accuracy) of each player, when available.\n", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "opening", + "description": "Include the opening name.\n\nExample: `[Opening \"King's Gambit Accepted, King's Knight Gambit\"]`\n", + "schema": { + "type": "boolean", + "default": false + } + } + ], + "responses": { + "200": { + "description": "The list of games of an Arena tournament.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/x-chess-pgn": { + "schema": { + "$ref": "#/components/schemas/GamePgn" + } + }, + "application/x-ndjson": { + "schema": { + "$ref": "#/components/schemas/GameJson" + } + } + } + } + } + } + }, + "/api/tournament/{id}/results": { + "get": { + "operationId": "resultsByTournament", + "summary": "Get results of an Arena tournament", + "description": "Players of an Arena tournament, with their score and performance, sorted by rank (best first).\n\n**Players are streamed as [ndjson](#section/Introduction/Streaming-with-ND-JSON)**, i.e. one JSON object per line.\n\nIf called on an ongoing tournament, results can be inconsistent\ndue to ranking changes while the players are being streamed.\nUse on finished tournaments for guaranteed consistency.\n", + "tags": [ + "Arena tournaments" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "id", + "description": "The tournament ID.", + "schema": { + "type": "string" + }, + "required": true + }, + { + "in": "query", + "name": "nb", + "description": "Max number of players to fetch", + "schema": { + "type": "integer", + "minimum": 1 + } + }, + { + "in": "query", + "name": "sheet", + "description": "Add a `sheet` field to the player document.\nIt's an expensive server computation that slows down the stream.\n", + "schema": { + "type": "boolean", + "default": false + } + } + ], + "responses": { + "200": { + "description": "The results of the Arena tournament.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/x-ndjson": { + "schema": { + "example": { + "rank": 4, + "score": 389, + "rating": 2618, + "username": "opperwezen", + "title": "IM", + "performance": 2423, + "team": "coders" + } + } + } + } + } + } + } + }, + "/api/tournament/{id}/teams": { + "get": { + "operationId": "teamsByTournament", + "summary": "Get team standing of a team battle", + "description": "Teams of a team battle tournament, with top players, sorted by rank (best first).\n", + "tags": [ + "Arena tournaments" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "id", + "description": "The tournament ID.", + "schema": { + "type": "string" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The list of teams of a team battle tournament, with their respective top players.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "example": { + "id": "CdPg1ey4", + "teams": [ + { + "rank": 1, + "id": "cat-lovers", + "score": 842, + "players": [ + { + "user": { + "name": "lizen69", + "id": "lizen69" + }, + "score": 54 + }, + { + "user": { + "name": "lizen249", + "id": "lizen249" + } + } + ] + } + ] + } + } + } + } + } + } + } + }, + "/api/user/{username}/tournament/created": { + "get": { + "operationId": "apiUserNameTournamentCreated", + "summary": "Get tournaments created by a user", + "description": "Get all tournaments created by a given user.\n\nTournaments are sorted by reverse chronological order of start date (last starting first).\n\nTournaments are streamed as [ndjson](#section/Introduction/Streaming-with-ND-JSON).\n", + "tags": [ + "Arena tournaments" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "username", + "description": "The user whose created tournaments to fetch", + "schema": { + "type": "string" + }, + "required": true + }, + { + "in": "query", + "name": "status", + "description": "Include tournaments in the given status: \"Created\" (10), \"Started\" (20), \"Finished\" (30)\n\nYou can add this parameter more than once to include tournaments in different statuses.\n\nExample: `?status=10&status=20`\n", + "schema": { + "type": "integer", + "enum": [ + 10, + 20, + 30 + ] + }, + "required": false + } + ], + "responses": { + "200": { + "description": "The list of tournaments created by the user.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/x-ndjson": { + "schema": { + "$ref": "#/components/schemas/ArenaTournament" + } + } + } + } + } + } + }, + "/api/swiss/new/{teamId}": { + "post": { + "operationId": "apiSwissNew", + "summary": "Create a new Swiss tournament", + "description": "Create a Swiss tournament for your team.\n\nThis endpoint mirrors the Swiss tournament form from your team pagee.\n\nYou can create up to 12 tournaments per day.\n\nAdditional restrictions:\n - clock.limit + clock.increment > 0\n - 15s and 0+1 variant tournaments cannot be rated\n", + "tags": [ + "Swiss tournaments" + ], + "security": [ + { + "OAuth2": [ + "tournament:write" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "teamId", + "description": "ID of the team", + "schema": { + "type": "string" + }, + "required": true + } + ], + "requestBody": { + "description": "Parameters of the tournament", + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The tournament name. Leave empty to get a random Grandmaster name", + "minLength": 2, + "maxLength": 30 + }, + "clock.limit": { + "type": "number", + "description": "Clock initial time in seconds", + "example": 300, + "enum": [ + 0, + 15, + 30, + 45, + 60, + 90, + 120, + 180, + 240, + 300, + 360, + 420, + 480, + 600, + 900, + 1200, + 1500, + 1800, + 2400, + 3000, + 3600, + 4200, + 4800, + 5400, + 6000, + 6600, + 7200, + 7800, + 8400, + 9000, + 9600, + 10200, + 10800 + ] + }, + "clock.increment": { + "type": "integer", + "description": "Clock increment in seconds", + "example": 1, + "minimum": 0, + "maximum": 120 + }, + "nbRounds": { + "type": "integer", + "description": "Maximum number of rounds to play", + "minimum": 3, + "maximum": 100 + }, + "startsAt": { + "type": "integer", + "description": "Timestamp in milliseconds to start the tournament at a given date and time. By default, it starts 10 minutes after creation." + }, + "roundInterval": { + "type": "integer", + "description": "How long to wait between each round, in seconds.\n\nSet to 99999999 to manually schedule each round from the tournament UI.\n\nIf empty or -1, a sensible value is picked automatically.\n", + "enum": [ + -1, + 5, + 10, + 20, + 30, + 45, + 60, + 120, + 180, + 300, + 600, + 900, + 1200, + 1800, + 2700, + 3600, + 86400, + 172800, + 604800, + 99999999 + ] + }, + "variant": { + "$ref": "#/components/schemas/VariantKey" + }, + "position": { + "$ref": "#/components/schemas/FromPositionFEN" + }, + "description": { + "type": "string", + "description": "Anything you want to tell players about the tournament" + }, + "rated": { + "type": "boolean", + "description": "Games are rated and impact players ratings", + "default": true + }, + "password": { + "type": "string", + "description": "Make the tournament private and restrict access with a password." + }, + "forbiddenPairings": { + "type": "string", + "description": "Usernames of players that must not play together.\n\nTwo usernames per line, separated by a space.\n" + }, + "manualPairings": { + "type": "string", + "description": "Manual pairings for the next round.\n\nTwo usernames per line, separated by a space. Example:\n```\nPlayerA PlayerB\nPlayerC PlayerD\n```\n\nTo give a bye (1 point) to a player instead of a pairing, add a line like so:\n```\nPlayerE 1\n```\n\nMissing players will be considered absent and get zero points.\n" + }, + "chatFor": { + "type": "number", + "description": "Who can read and write in the chat.\n- 0 = No-one\n- 10 = Only team leaders\n- 20 = Only team members\n- 30 = All Lichess players\n", + "default": 20 + }, + "conditions.minRating.rating": { + "type": "integer", + "description": "Minimum rating to join. Leave empty to let everyone join the tournament.", + "enum": [ + 1000, + 1100, + 1200, + 1300, + 1400, + 1500, + 1600, + 1700, + 1800, + 1900, + 2000, + 2100, + 2200, + 2300, + 2400, + 2500, + 2600 + ] + }, + "conditions.maxRating.rating": { + "type": "integer", + "description": "Maximum rating to join. Based on best rating reached in the last 7 days. Leave empty to let everyone join the tournament.", + "enum": [ + 2200, + 2100, + 2000, + 1900, + 1800, + 1700, + 1600, + 1500, + 1400, + 1300, + 1200, + 1100, + 1000, + 900, + 800 + ] + }, + "conditions.nbRatedGame.nb": { + "type": "integer", + "description": "Minimum number of rated games required to join.", + "minimum": 0, + "maximum": 200 + }, + "conditions.allowList": { + "type": "string", + "description": "Predefined list of usernames that are allowed to join, separated by commas.\nIf this list is non-empty, then usernames absent from this list will be forbidden to join.\nAdding `%titled` to the list additionally allows any titled player to join.\nExample: `thibault,german11,%titled`\n" + } + }, + "required": [ + "clock.limit", + "clock.increment", + "nbRounds" + ] + } + } + } + }, + "responses": { + "200": { + "description": "The Swiss tournament was successfully created.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SwissTournament" + } + } + } + }, + "400": { + "description": "The creation of the Swiss tournament failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/swiss/{id}": { + "parameters": [ + { + "in": "path", + "name": "id", + "description": "The Swiss tournament ID.", + "schema": { + "type": "string" + }, + "required": true + } + ], + "get": { + "operationId": "swiss", + "summary": "Get info about a Swiss tournament", + "description": "Get detailed info about a Swiss tournament.\n", + "tags": [ + "Swiss tournaments" + ], + "security": [], + "responses": { + "200": { + "description": "The information of the Swiss tournament.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SwissTournament" + } + } + } + } + } + } + }, + "/api/swiss/{id}/edit": { + "post": { + "operationId": "apiSwissUpdate", + "summary": "Update a Swiss tournament", + "description": "Update a Swiss tournament.\n\nBe mindful not to make important changes to ongoing tournaments.\n\nAdditional restrictions:\n - clock.limit + clock.increment > 0\n - 15s and 0+1 variant tournaments cannot be rated\n", + "tags": [ + "Swiss tournaments" + ], + "security": [ + { + "OAuth2": [ + "tournament:write" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "id", + "description": "The tournament ID.", + "schema": { + "type": "string", + "example": "hL7vMrFQ" + }, + "required": true + } + ], + "requestBody": { + "description": "Parameters of the tournament", + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The tournament name. Leave empty to get a random Grandmaster name", + "minLength": 2, + "maxLength": 30 + }, + "clock.limit": { + "type": "number", + "description": "Clock initial time in seconds", + "example": 300, + "enum": [ + 0, + 15, + 30, + 45, + 60, + 90, + 120, + 180, + 240, + 300, + 360, + 420, + 480, + 600, + 900, + 1200, + 1500, + 1800, + 2400, + 3000, + 3600, + 4200, + 4800, + 5400, + 6000, + 6600, + 7200, + 7800, + 8400, + 9000, + 9600, + 10200, + 10800 + ] + }, + "clock.increment": { + "type": "integer", + "description": "Clock increment in seconds", + "example": 1, + "minimum": 0, + "maximum": 120 + }, + "nbRounds": { + "type": "integer", + "description": "Maximum number of rounds to play", + "minimum": 3, + "maximum": 100 + }, + "startsAt": { + "type": "integer", + "description": "Timestamp in milliseconds to start the tournament at a given date and time. By default, it starts 10 minutes after creation." + }, + "roundInterval": { + "type": "integer", + "description": "How long to wait between each round, in seconds.\n\nSet to 99999999 to manually schedule each round from the tournament UI, or [with the API](#tag/Swiss-tournaments/operation/apiSwissScheduleNextRound).\n\nIf empty or -1, a sensible value is picked automatically.\n", + "enum": [ + -1, + 5, + 10, + 20, + 30, + 45, + 60, + 120, + 180, + 300, + 600, + 900, + 1200, + 1800, + 2700, + 3600, + 86400, + 172800, + 604800, + 99999999 + ] + }, + "variant": { + "$ref": "#/components/schemas/VariantKey" + }, + "description": { + "type": "string", + "description": "Anything you want to tell players about the tournament" + }, + "rated": { + "type": "boolean", + "description": "Games are rated and impact players ratings", + "default": true + }, + "password": { + "type": "string", + "description": "Make the tournament private and restrict access with a password." + }, + "forbiddenPairings": { + "type": "string", + "description": "Usernames of players that must not play together.\n\nTwo usernames per line, separated by a space.\n" + }, + "manualPairings": { + "type": "string", + "description": "Manual pairings for the next round.\n\nTwo usernames per line, separated by a space.\nPresent players without a valid pairing will be given a bye, which is worth 1 point.\nForfeited players will get 0 points.\n" + }, + "chatFor": { + "type": "number", + "description": "Who can read and write in the chat.\n- 0 = No-one\n- 10 = Only team leaders\n- 20 = Only team members\n- 30 = All Lichess players\n", + "default": 20 + }, + "conditions.minRating.rating": { + "type": "integer", + "description": "Minimum rating to join. Leave empty to let everyone join the tournament.", + "enum": [ + 1000, + 1100, + 1200, + 1300, + 1400, + 1500, + 1600, + 1700, + 1800, + 1900, + 2000, + 2100, + 2200, + 2300, + 2400, + 2500, + 2600 + ] + }, + "conditions.maxRating.rating": { + "type": "integer", + "description": "Maximum rating to join. Based on best rating reached in the last 7 days. Leave empty to let everyone join the tournament.", + "enum": [ + 2200, + 2100, + 2000, + 1900, + 1800, + 1700, + 1600, + 1500, + 1400, + 1300, + 1200, + 1100, + 1000, + 900, + 800 + ] + }, + "conditions.nbRatedGame.nb": { + "type": "integer", + "description": "Minimum number of rated games required to join.", + "minimum": 0, + "maximum": 200 + }, + "conditions.allowList": { + "type": "string", + "description": "Predefined list of usernames that are allowed to join, separated by commas.\nIf this list is non-empty, then usernames absent from this list will be forbidden to join.\nAdding `%titled` to the list additionally allows any titled player to join.\nExample: `thibault,german11,%titled`\n" + } + }, + "required": [ + "clock.limit", + "clock.increment", + "nbRounds" + ] + } + } + } + }, + "responses": { + "200": { + "description": "The Swiss tournament was successfully updated.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SwissTournament" + } + } + } + }, + "400": { + "description": "Updating the swiss failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "This user cannot update this Swiss.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SwissUnauthorisedEdit" + } + } + } + } + } + } + }, + "/api/swiss/{id}/schedule-next-round": { + "post": { + "operationId": "apiSwissScheduleNextRound", + "summary": "Manually schedule the next round", + "description": "Manually schedule the next round date and time of a Swiss tournament.\n\nThis sets the `roundInterval` field to `99999999`, i.e. manual scheduling.\n\nAll further rounds will need to be manually scheduled, unless the `roundInterval` field is changed back to automatic scheduling.\n", + "tags": [ + "Swiss tournaments" + ], + "security": [ + { + "OAuth2": [ + "tournament:write" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "id", + "description": "The tournament ID.", + "schema": { + "type": "string", + "example": "hL7vMrFQ" + }, + "required": true + } + ], + "requestBody": { + "description": "Parameters of the tournament", + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "date": { + "type": "integer", + "description": "Timestamp in milliseconds to start the next round at a given date and time." + } + } + } + } + } + }, + "responses": { + "204": { + "description": "The Swiss tournament was successfully updated.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + } + }, + "400": { + "description": "Updating the swiss failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "This user cannot update this Swiss.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SwissUnauthorisedEdit" + } + } + } + } + } + } + }, + "/api/swiss/{id}/join": { + "post": { + "operationId": "apiSwissJoin", + "summary": "Join a Swiss tournament", + "description": "Join a Swiss tournament, possibly with a password.\n", + "tags": [ + "Swiss tournaments" + ], + "security": [ + { + "OAuth2": [ + "tournament:write" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "id", + "description": "The tournament ID.", + "schema": { + "type": "string", + "example": "hL7vMrFQ" + }, + "required": true + } + ], + "requestBody": { + "description": "You may need these depending on the tournament to join", + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "password": { + "type": "string", + "description": "The tournament password, if one is required" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "The tournament was successfully joined.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "400": { + "description": "Joining the tournament failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/swiss/{id}/withdraw": { + "post": { + "operationId": "apiSwissWithdraw", + "summary": "Pause or leave a swiss tournament", + "description": "Leave a future Swiss tournament, or take a break on an ongoing Swiss tournament.\nIt's possible to join again later. Points are preserved.\n", + "tags": [ + "Swiss tournaments" + ], + "security": [ + { + "OAuth2": [ + "tournament:write" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "id", + "description": "The tournament ID.", + "schema": { + "type": "string", + "example": "hL7vMrFQ" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The tournament was successfully paused or left.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + } + } + } + }, + "/api/swiss/{id}/terminate": { + "post": { + "operationId": "apiSwissTerminate", + "summary": "Terminate a Swiss tournament", + "description": "Terminate a Swiss tournament\n", + "tags": [ + "Swiss tournaments" + ], + "security": [ + { + "OAuth2": [ + "tournament:write" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "id", + "description": "The Swiss tournament ID.", + "schema": { + "type": "string", + "example": "W5FrxusN" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The Swiss tournament was successfully terminated.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "400": { + "description": "Terminating the Swiss tournament failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/swiss/{id}.trf": { + "get": { + "operationId": "swissTrf", + "summary": "Export TRF of a Swiss tournament", + "description": "Download a tournament in the Tournament Report File format, the FIDE standard.\n\nDocumentation: \n\nExample: \n", + "tags": [ + "Swiss tournaments" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "id", + "description": "The tournament ID.", + "schema": { + "type": "string" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The TRF representation of a Swiss tournament.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "text/plain": { + "schema": { + "type": "string" + } + } + } + } + } + } + }, + "/api/swiss/{id}/games": { + "get": { + "operationId": "gamesBySwiss", + "summary": "Export games of a Swiss tournament", + "description": "Download games of a swiss tournament in PGN or [ndjson](#section/Introduction/Streaming-with-ND-JSON) format.\n\nGames are sorted by reverse chronological order (last round first).\n\nThe game stream is throttled, depending on who is making the request:\n - Anonymous request: 20 games per second\n - [OAuth2 authenticated](#section/Introduction/Authentication) request: 30 games per second\n", + "tags": [ + "Swiss tournaments" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "id", + "description": "The tournament ID.", + "schema": { + "type": "string" + }, + "required": true + }, + { + "in": "query", + "name": "player", + "description": "Only the games played by a given player", + "schema": { + "type": "string" + } + }, + { + "in": "query", + "name": "moves", + "description": "Include the PGN moves.", + "schema": { + "type": "boolean", + "default": true + } + }, + { + "in": "query", + "name": "pgnInJson", + "description": "Include the full PGN within the JSON response, in a `pgn` field.", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "tags", + "description": "Include the PGN tags.", + "schema": { + "type": "boolean", + "default": true + } + }, + { + "in": "query", + "name": "clocks", + "description": "Include clock status when available.\n\nEither as PGN comments: `2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] }`\n\nOr in a `clocks` JSON field, as centisecond integers, depending on the response type.\n", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "evals", + "description": "Include analysis evaluations and comments, when available.\n\nEither as PGN comments: `12. Bxf6 { [%eval 0.23] } a3 { [%eval -1.09] }`\n\nOr in an `analysis` JSON field, depending on the response type.\n", + "schema": { + "type": "boolean", + "default": true + } + }, + { + "in": "query", + "name": "accuracy", + "description": "Include [accuracy percent](https://lichess.org/page/accuracy) of each player, when available.\n", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "opening", + "description": "Include the opening name.\n\nExample: `[Opening \"King's Gambit Accepted, King's Knight Gambit\"]`\n", + "schema": { + "type": "boolean", + "default": false + } + } + ], + "responses": { + "200": { + "description": "The list of games of a Swiss tournament.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/x-chess-pgn": { + "schema": { + "$ref": "#/components/schemas/GamePgn" + } + }, + "application/x-ndjson": { + "schema": { + "$ref": "#/components/schemas/GameJson" + } + } + } + } + } + } + }, + "/api/swiss/{id}/results": { + "get": { + "operationId": "resultsBySwiss", + "summary": "Get results of a swiss tournament", + "description": "Players of a swiss tournament, with their score and performance, sorted by rank (best first).\n\nPlayers are streamed as [ndjson](#section/Introduction/Streaming-with-ND-JSON).\n\nIf called on an ongoing tournament, results can be inconsistent\ndue to ranking changes while the players are being streamed.\nUse on finished tournaments for guaranteed consistency.\n", + "tags": [ + "Swiss tournaments" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "id", + "description": "The tournament ID.", + "schema": { + "type": "string" + }, + "required": true + }, + { + "in": "query", + "name": "nb", + "description": "Max number of players to fetch", + "schema": { + "type": "integer", + "minimum": 1 + } + } + ], + "responses": { + "200": { + "description": "The results of a Swiss tournament.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/x-ndjson": { + "schema": { + "example": { + "rank": 4, + "points": 8.5, + "tieBreak": 77, + "rating": 2618, + "username": "opperwezen", + "title": "IM", + "performance": 2423 + } + } + } + } + } + } + } + }, + "/api/team/{teamId}/swiss": { + "get": { + "operationId": "apiTeamSwiss", + "summary": "Get team swiss tournaments", + "description": "Get all swiss tournaments of a team.\n\nTournaments are sorted by reverse chronological order of start date (last starting first).\n\nTournaments are streamed as [ndjson](#section/Introduction/Streaming-with-ND-JSON).\n", + "tags": [ + "Teams", + "Swiss tournaments" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "teamId", + "schema": { + "type": "string" + }, + "required": true, + "example": "coders" + }, + { + "in": "query", + "name": "max", + "description": "How many tournaments to download.", + "schema": { + "type": "integer", + "minimum": 1, + "default": 100 + } + } + ], + "responses": { + "200": { + "description": "The list of Swiss tournaments of a team.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/nd-json": { + "schema": { + "$ref": "#/components/schemas/SwissTournament" + } + } + } + } + } + } + }, + "/study/{studyId}/{chapterId}.pgn": { + "get": { + "operationId": "studyChapterPgn", + "summary": "Export one study chapter", + "description": "Download one study chapter in PGN format.\n", + "tags": [ + "Studies" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "studyId", + "description": "The study ID (8 characters).", + "required": true, + "schema": { + "type": "string" + } + }, + { + "in": "path", + "name": "chapterId", + "description": "The chapter ID (8 characters).", + "required": true, + "schema": { + "type": "string" + } + }, + { + "in": "query", + "name": "clocks", + "description": "Include clock comments in the PGN moves, when available.\n\nExample: `2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] }`\n", + "schema": { + "type": "boolean", + "default": true + } + }, + { + "in": "query", + "name": "comments", + "description": "Include analysis and annotator comments in the PGN moves, when available.\n\nExample: `12. Bxf6 { [%eval 0.23] } a3 { White is in a pickle. }`\n", + "schema": { + "type": "boolean", + "default": true + } + }, + { + "in": "query", + "name": "variations", + "description": "Include non-mainline moves, when available.\n\nExample: `4. d4 Bb4+ (4... Nc6 5. Nf3 Bb4+ 6. Bd2 (6. Nbd2 O-O 7. O-O) 6... Bd6) 5. Nd2`\n", + "schema": { + "type": "boolean", + "default": true + } + }, + { + "in": "query", + "name": "source", + "description": "Add a `Source` PGN tag with the study chapter URL.\n\nExample: `[Source \"https://lichess.org/study/4NBHImfM/1Tk4IyTz\"]`\n", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "orientation", + "description": "Add a `Orientation` PGN tag with the chapter predefined orientation.\n\nExample: `[Orientation \"white\"]`\n", + "schema": { + "type": "boolean", + "default": false + } + } + ], + "responses": { + "200": { + "description": "The chapter of the study.", + "content": { + "application/x-chess-pgn": { + "schema": { + "$ref": "#/components/schemas/StudyPgn" + } + } + } + } + } + } + }, + "/api/study/{studyId}.pgn": { + "get": { + "operationId": "studyAllChaptersPgn", + "summary": "Export all chapters", + "description": "Download all chapters of a study in PGN format.\n", + "tags": [ + "Studies" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "studyId", + "description": "The study ID (8 characters).", + "required": true, + "schema": { + "type": "string" + } + }, + { + "in": "query", + "name": "clocks", + "description": "Include clock comments in the PGN moves, when available.\n\nExample: `2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] }`\n", + "schema": { + "type": "boolean", + "default": true + } + }, + { + "in": "query", + "name": "comments", + "description": "Include analysis and annotator comments in the PGN moves, when available.\n\nExample: `12. Bxf6 { [%eval 0.23] } a3 { White is in a pickle. }`\n", + "schema": { + "type": "boolean", + "default": true + } + }, + { + "in": "query", + "name": "variations", + "description": "Include non-mainline moves, when available.\n\nExample: `4. d4 Bb4+ (4... Nc6 5. Nf3 Bb4+ 6. Bd2 (6. Nbd2 O-O 7. O-O) 6... Bd6) 5. Nd2`\n", + "schema": { + "type": "boolean", + "default": true + } + }, + { + "in": "query", + "name": "source", + "description": "Add a `Source` PGN tag with the study chapter URL.\n\nExample: `[Source \"https://lichess.org/study/4NBHImfM/1Tk4IyTz\"]`\n", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "orientation", + "description": "Add a `Orientation` PGN tag with the chapter predefined orientation.\n\nExample: `[Orientation \"white\"]`\n", + "schema": { + "type": "boolean", + "default": false + } + } + ], + "responses": { + "200": { + "description": "The PGN representation of the study.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/x-chess-pgn": { + "schema": { + "$ref": "#/components/schemas/StudyPgn" + } + } + } + } + } + } + }, + "/study/by/{username}/export.pgn": { + "get": { + "operationId": "studyExportAllPgn", + "summary": "Export all studies of a user", + "description": "Download all chapters of all studies of a user in PGN format.\n\nIf authenticated, then all public, unlisted, and private studies are included.\n\nIf not, only public, listed studies are included.\n", + "tags": [ + "Studies" + ], + "security": [ + { + "OAuth2": [ + "study:read" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "username", + "description": "The user whose studies we export", + "required": true, + "schema": { + "type": "string" + } + }, + { + "in": "query", + "name": "clocks", + "description": "Include clock comments in the PGN moves, when available.\n\nExample: `2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] }`\n", + "schema": { + "type": "boolean", + "default": true + } + }, + { + "in": "query", + "name": "comments", + "description": "Include analysis and annotator comments in the PGN moves, when available.\n\nExample: `12. Bxf6 { [%eval 0.23] } a3 { White is in a pickle. }`\n", + "schema": { + "type": "boolean", + "default": true + } + }, + { + "in": "query", + "name": "variations", + "description": "Include non-mainline moves, when available.\n\nExample: `4. d4 Bb4+ (4... Nc6 5. Nf3 Bb4+ 6. Bd2 (6. Nbd2 O-O 7. O-O) 6... Bd6) 5. Nd2`\n", + "schema": { + "type": "boolean", + "default": true + } + }, + { + "in": "query", + "name": "source", + "description": "Add a `Source` PGN tag with the study chapter URL.\n\nExample: `[Source \"https://lichess.org/study/4NBHImfM/1Tk4IyTz\"]`\n", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "orientation", + "description": "Add a `Orientation` PGN tag with the chapter predefined orientation.\n\nExample: `[Orientation \"white\"]`\n", + "schema": { + "type": "boolean", + "default": false + } + } + ], + "responses": { + "200": { + "description": "The studies of the user.", + "content": { + "application/x-chess-pgn": { + "schema": { + "$ref": "#/components/schemas/StudyPgn" + } + } + } + } + } + } + }, + "/api/broadcast": { + "get": { + "operationId": "broadcastIndex", + "summary": "Get official broadcasts", + "description": "Get all incoming, ongoing, and finished official broadcasts.\nThe broadcasts are sorted by start date, most recent first.\n\nBroadcasts are streamed as [ndjson](#section/Introduction/Streaming-with-ND-JSON).\n", + "tags": [ + "Broadcasts" + ], + "security": [], + "parameters": [ + { + "in": "query", + "name": "nb", + "description": "Max number of broadcasts to fetch", + "schema": { + "type": "integer", + "default": 20, + "minimum": 1 + } + } + ], + "responses": { + "200": { + "description": "The list of official broadcasts.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/x-ndjson": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/BroadcastTour" + } + } + } + } + } + } + } + }, + "/broadcast/new": { + "post": { + "operationId": "broadcastTourCreate", + "summary": "Create a broadcast tournament", + "description": "Create a new broadcast tournament to relay external games.\nThis endpoint accepts the same form data as the [web form](https://lichess.org/broadcast/new).\n", + "tags": [ + "Broadcasts" + ], + "security": [ + { + "OAuth2": [ + "study:write" + ] + } + ], + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the broadcast tournament. Length must be between 3 and 80 characters.\n\nExample: `Sinquefield Cup`\n" + }, + "description": { + "type": "string", + "description": "Short description of the broadcast tournament. Length must be between 3 and 400 characters.\n\nExample: `An 11 round classical tournament featuring the 9 highest rated players in the world. Including Carlsen, Caruana, Ding, Aronian, Nakamura and more.`\n" + }, + "markdown": { + "type": "string", + "description": "Optional long description of the broadcast. Markdown is supported. Length must be less than 20,000 characters." + }, + "official": { + "type": "boolean", + "description": "For Lichess internal usage only. You are not allowed to use this flag. If you do it, we will have to call the police." + } + }, + "required": [ + "name", + "description" + ] + } + } + } + }, + "responses": { + "200": { + "description": "The broadcast tournament was successfully created.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BroadcastTour" + } + } + } + }, + "400": { + "description": "The creation of the broadcast tournament failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/broadcast/{slug}/{broadcastTournamentId}": { + "get": { + "operationId": "broadcastTourGet", + "summary": "Get your broadcast tournament", + "description": "Get information about a broadcast tournament.\n", + "tags": [ + "Broadcasts" + ], + "security": [ + { + "OAuth2": [ + "study:read" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "slug", + "description": "The broadcast tournament slug. Only used for SEO, the slug can be safely replaced by `-`. Only the `broadcastTournamentId` is actually used.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "in": "path", + "name": "broadcastTournamentId", + "description": "The broadcast tournament ID (8 characters).", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The information about the broadcast tournament.", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/BroadcastTour" + } + } + } + } + } + } + } + }, + "/broadcast/{broadcastTournamentId}/edit": { + "post": { + "operationId": "broadcastTourUpdate", + "summary": "Update your broadcast tournament", + "description": "Update information about a broadcast tournament that you created.\nThis endpoint accepts the same form data as the web form.\nAll fields must be populated with data. Missing fields will override the broadcast with empty data.\n", + "tags": [ + "Broadcasts" + ], + "security": [ + { + "OAuth2": [ + "study:write" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "broadcastTournamentId", + "description": "The broadcast ID (8 characters).", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the broadcast tournament. Length must be between 3 and 80 characters.\n\nExample: `Sinquefield Cup`\n" + }, + "description": { + "type": "string", + "description": "Short description of the broadcast tournament. Length must be between 3 and 400 characters.\n\nExample: `An 11 round classical tournament featuring the 9 highest rated players in the world. Including Carlsen, Caruana, Ding, Aronian, Nakamura and more.`\n" + }, + "markdown": { + "type": "string", + "description": "Optional long description of the broadcast tournament. Markdown is supported. Length must be less than 20,000 characters." + }, + "official": { + "type": "boolean", + "description": "For Lichess internal usage only. You are not allowed to use this flag. If you do it, we will have to call the police." + } + }, + "required": [ + "name", + "description" + ] + } + } + } + }, + "responses": { + "200": { + "description": "The broadcast tournament was successfully edited.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "400": { + "description": "The edition of the broadcast tournament failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/broadcast/{broadcastTournamentId}/new": { + "post": { + "operationId": "broadcastRoundCreate", + "summary": "Create a broadcast round", + "description": "Create a new broadcast round to relay external games.\nThis endpoint accepts the same form data as the web form.\n", + "tags": [ + "Broadcasts" + ], + "security": [ + { + "OAuth2": [ + "study:write" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "broadcastTournamentId", + "description": "The broadcast tournament ID (8 characters).", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the broadcast round. Length must be between 3 and 80 characters.\n\nExample: `Round 1`\n" + }, + "syncUrl": { + "type": "string", + "description": "URL that Lichess will poll to get updates about the games. It must be publicly accessible from the Internet.\n\nExample: `https://myserver.org/myevent/round-10/games.pgn`\n\nIf the syncUrl is missing, then the broadcast needs to be fed by [pushing PGN to it](#operation/broadcastPush).\n" + }, + "startsAt": { + "type": "integer", + "description": "Timestamp in milliseconds of broadcast round start. Leave empty to manually start the broadcast round.\n\nExample: `1356998400070`\n", + "minimum": 1356998400070 + } + }, + "required": [ + "name" + ] + } + } + } + }, + "responses": { + "200": { + "description": "The broadcast round was successfully created.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BroadcastRound" + } + } + } + }, + "400": { + "description": "The creation of the broadcast failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/broadcast/{broadcastTournamentSlug}/{broadcastRoundSlug}/{broadcastRoundId}": { + "get": { + "operationId": "broadcastRoundGet", + "summary": "Get your broadcast round", + "description": "Get information about a broadcast round.\n", + "tags": [ + "Broadcasts" + ], + "security": [ + { + "OAuth2": [ + "study:read" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "broadcastTournamentSlug", + "description": "The broadcast tournament slug. Only used for SEO, the slug can be safely replaced by `-`. Only the `broadcastRoundId` is actually used.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "in": "path", + "name": "broadcastRoundSlug", + "description": "The broadcast round slug. Only used for SEO, the slug can be safely replaced by `-`. Only the `broadcastRoundId` is actually used.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "in": "path", + "name": "broadcastRoundId", + "description": "The broadcast Round ID (8 characters).", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The information about the broadcast round.", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/BroadcastRound" + } + } + } + } + } + } + } + }, + "/broadcast/round/{broadcastRoundId}/edit": { + "post": { + "operationId": "broadcastRoundUpdate", + "summary": "Update your broadcast round", + "description": "Update information about a broadcast round that you created.\nThis endpoint accepts the same form data as the web form.\nAll fields must be populated with data. Missing fields will override the broadcast with empty data.\nFor instance, if you omit `startDate`, then any pre-existing start date will be removed.\n", + "tags": [ + "Broadcasts" + ], + "security": [ + { + "OAuth2": [ + "study:write" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "broadcastRoundId", + "description": "The broadcast round ID (8 characters).", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the broadcast round. Length must be between 3 and 80 characters.\n\nExample: `Round 10`\n" + }, + "syncUrl": { + "type": "string", + "description": "URL that Lichess will poll to get updates about the games. It must be publicly accessible from the Internet.\n\nExample: `https://myserver.org/myevent/round-10/games.pgn`\n" + }, + "startsAt": { + "type": "integer", + "description": "Timestamp in milliseconds of broadcast start. Leave empty to manually start the broadcast.\n\nExample: `1356998400070`\n", + "minimum": 1356998400070 + } + }, + "required": [ + "name" + ] + } + } + } + }, + "responses": { + "200": { + "description": "The broadcast round was successfully edited.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "400": { + "description": "The edition of the broadcast tournament failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/broadcast/round/{broadcastRoundId}/push": { + "post": { + "operationId": "broadcastPush", + "summary": "Push PGN to your broadcast round", + "description": "Update your broadcast with new PGN.\nOnly for broadcast without a source URL.\n", + "tags": [ + "Broadcasts" + ], + "security": [ + { + "OAuth2": [ + "study:write" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "broadcastRoundId", + "description": "The broadcast round ID (8 characters).", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "description": "The PGN. It can contain up to 64 games, separated by a double new line.", + "required": true, + "content": { + "text/plain": { + "schema": { + "type": "string" + } + } + } + }, + "responses": { + "200": { + "description": "The broadcast was successfully updated.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Ok" + } + } + } + } + } + } + } + }, + "/api/stream/broadcast/round/{broadcastRoundId}.pgn": { + "get": { + "operationId": "broadcastStreamRoundPgn", + "summary": "Stream an ongoing broadcast tournament as PGN", + "description": "This streaming endpoint first sends all games of a broadcast tournament in PGN format.\n\nThen, it waits for new moves to be played. As soon as it happens, the entire PGN of the game is sent to the stream.\n\nThe stream will also send PGNs when games are added to the tournament.\n\nThis is the best way to get updates about an ongoing tournament. Streaming means no polling,\nand no pollings means no latency, and minimum impact on the server.\n", + "tags": [ + "Broadcasts" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "broadcastRoundId", + "description": "The broadcast round ID (8 characters).", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The PGN representation of the tournament games, then the PGNs of games as they are updated.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/x-chess-pgn": { + "schema": { + "$ref": "#/components/schemas/StudyPgn" + } + } + } + } + } + } + }, + "/api/broadcast/round/{broadcastRoundId}.pgn": { + "get": { + "operationId": "broadcastRoundPgn", + "summary": "Export one round as PGN", + "description": "Download all games of a single round of a broadcast tournament in PGN format.\n\nYou *could* poll this endpoint to get updates about a tournament, but it would be slow,\nand very inneficient.\n\nInstead, consider [streaming the tournament](#operation/broadcastStreamRoundPgn) to get\na new PGN every time a game is updated, in real-time.\n", + "tags": [ + "Broadcasts" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "broadcastRoundId", + "description": "The round ID (8 characters).", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The PGN representation of the round.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/x-chess-pgn": { + "schema": { + "$ref": "#/components/schemas/StudyPgn" + } + } + } + } + } + } + }, + "/api/broadcast/{broadcastTournamentId}.pgn": { + "get": { + "operationId": "broadcastAllRoundsPgn", + "summary": "Export all rounds as PGN", + "description": "Download all games of all rounds of a broadcast in PGN format.\n\nYou may want to [download only the games of a single round](#operation/broadcastRoundPgn) instead.\n", + "tags": [ + "Broadcasts" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "broadcastTournamentId", + "description": "The broadcast tournament ID (8 characters).", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The PGN representation of the broadcast.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/x-chess-pgn": { + "schema": { + "$ref": "#/components/schemas/StudyPgn" + } + } + } + } + } + } + }, + "/api/simul": { + "get": { + "operationId": "apiSimul", + "summary": "Get current simuls", + "description": "Get recently finished, ongoing, and upcoming simuls.\n", + "tags": [ + "Simuls" + ], + "security": [], + "responses": { + "200": { + "description": "The list of simuls.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Simul" + } + } + } + } + } + } + } + }, + "/api/team/{teamId}": { + "get": { + "operationId": "teamShow", + "summary": "Get a single team", + "description": "Infos about a team", + "tags": [ + "Teams" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "teamId", + "schema": { + "type": "string" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The information about the team.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Team" + } + } + } + } + } + } + }, + "/api/team/all": { + "get": { + "operationId": "teamAll", + "summary": "Get popular teams", + "description": "Paginator of the most popular teams.\n", + "tags": [ + "Teams" + ], + "security": [], + "parameters": [ + { + "in": "query", + "name": "page", + "schema": { + "type": "number", + "example": 1, + "default": 1 + } + } + ], + "responses": { + "200": { + "description": "A paginated list of the most popular teams.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "currentPage": { + "type": "number", + "example": 4 + }, + "maxPerPage": { + "type": "number", + "example": 15 + }, + "currentPageResults": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Team" + } + }, + "nbResults": { + "type": "number", + "example": 205194 + }, + "previousPage": { + "type": [ + "number", + "null" + ], + "example": 3 + }, + "nextPage": { + "type": [ + "number", + "null" + ], + "example": 5 + }, + "nbPages": { + "type": "number", + "example": 13680 + } + } + } + } + } + } + } + } + }, + "/api/team/of/{username}": { + "get": { + "operationId": "teamOfUsername", + "summary": "Teams of a player", + "description": "All the teams a player is a member of.\n", + "tags": [ + "Teams" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "username", + "schema": { + "type": "string", + "example": "thibault" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The list of teams the user is a member of.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Team" + } + } + } + } + } + } + } + }, + "/api/team/search": { + "get": { + "operationId": "teamSearch", + "summary": "Search teams", + "description": "Paginator of team search results for a keyword.\n", + "tags": [ + "Teams" + ], + "security": [], + "parameters": [ + { + "in": "query", + "name": "text", + "schema": { + "type": "string", + "example": "coders" + } + }, + { + "in": "query", + "name": "page", + "schema": { + "type": "number", + "example": 1, + "default": 1 + } + } + ], + "responses": { + "200": { + "description": "The paginated list of teams.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Team" + } + } + } + } + } + } + } + }, + "/api/team/{teamId}/users": { + "get": { + "operationId": "teamIdUsers", + "summary": "Get members of a team", + "description": "Members are sorted by reverse chronological order of joining the team (most recent first).\nOAuth only required if the list of members is private.\n\nMembers are streamed as [ndjson](#section/Introduction/Streaming-with-ND-JSON).\n", + "tags": [ + "Users", + "Teams" + ], + "security": [ + { + "OAuth2": [ + "team:read" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "teamId", + "schema": { + "type": "string", + "example": "coders" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The list of users in the team.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/x-ndjson": { + "schema": { + "$ref": "#/components/schemas/UserExtended" + } + } + } + } + } + } + }, + "/api/team/{teamId}/arena": { + "get": { + "operationId": "apiTeamArena", + "summary": "Get team Arena tournaments", + "description": "Get all Arena tournaments relevant to a team.\n\nTournaments are sorted by reverse chronological order of start date (last starting first).\n\nTournaments are streamed as [ndjson](#section/Introduction/Streaming-with-ND-JSON).\n", + "tags": [ + "Teams", + "Arena tournaments" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "teamId", + "description": "ID of the team", + "schema": { + "type": "string" + }, + "required": true + }, + { + "in": "query", + "name": "max", + "description": "How many tournaments to download.", + "schema": { + "type": "integer", + "minimum": 1, + "default": 100 + } + } + ], + "responses": { + "200": { + "description": "The list of Arena tournaments of a team.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ArenaTournament" + } + } + } + } + } + } + } + }, + "/team/{teamId}/join": { + "post": { + "operationId": "teamIdJoin", + "summary": "Join a team", + "description": "Join a team.\nIf the team requires a password but the `password` field is incorrect,\nthen the call fails with `403 Forbidden`.\nSimilarly, if the team join policy requires a confirmation but the\n`message` parameter is not given, then the call fails with\n`403 Forbidden`.\n", + "tags": [ + "Teams" + ], + "security": [ + { + "OAuth2": [ + "team:write" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "teamId", + "schema": { + "type": "string", + "example": "coders" + }, + "required": true + } + ], + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "message": { + "type": "string", + "description": "Optional request message, if the team requires one." + }, + "password": { + "type": "string", + "description": "Optional password, if the team requires one." + } + } + } + } + } + }, + "responses": { + "200": { + "description": "The request to join a team was successfully sent.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + } + } + } + }, + "/team/{teamId}/quit": { + "post": { + "operationId": "teamIdQuit", + "summary": "Leave a team", + "description": "Leave a team.\n- \n", + "tags": [ + "Teams" + ], + "security": [ + { + "OAuth2": [ + "team:write" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "teamId", + "schema": { + "type": "string", + "example": "coders" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The logged in user has successfully left the team.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + } + } + } + }, + "/api/team/{teamId}/requests": { + "get": { + "operationId": "teamRequests", + "summary": "Get join requests", + "description": "Get pending join requests of your team", + "tags": [ + "Teams" + ], + "security": [ + { + "OAuth2": [ + "team:read" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "teamId", + "schema": { + "type": "string" + }, + "required": true + }, + { + "in": "query", + "name": "declined", + "description": "Get the declined join requests", + "schema": { + "type": "boolean", + "default": false + } + } + ], + "responses": { + "200": { + "description": "The list of pending join requests on your team", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/TeamRequestWithUser" + }, + "example": [ + { + "request": { + "date": 1644232474472, + "message": "Hello, I would like to join the team!", + "teamId": "coders", + "userId": "neio" + }, + "user": { + "createdAt": 1338509698620, + "id": "neio", + "perfs": { + "blitz": { + "games": 70, + "prog": 81, + "prov": true, + "rating": 1729, + "rd": 124 + }, + "chess960": { + "games": 2, + "prog": 0, + "prov": true, + "rating": 1528, + "rd": 266 + } + }, + "playTime": { + "total": 152902, + "tv": 20800 + }, + "profile": { + "bio": "yuwnt uyn", + "country": "AL", + "firstName": "wyutn w[fuyt", + "lastName": "ywut wyufth" + }, + "seenAt": 1644232201429, + "title": "NM", + "username": "Neio" + } + } + ] + } + } + } + } + } + } + }, + "/api/team/{teamId}/request/{userId}/accept": { + "post": { + "operationId": "teamRequestAccept", + "summary": "Accept join request", + "description": "Accept someone's request to join your team", + "tags": [ + "Teams" + ], + "security": [ + { + "OAuth2": [ + "team:lead" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "teamId", + "schema": { + "type": "string", + "example": "coders" + }, + "required": true + }, + { + "in": "path", + "name": "userId", + "schema": { + "type": "string", + "example": "neio" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The member has been added to the team.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + } + } + } + }, + "/api/team/{teamId}/request/{userId}/decline": { + "post": { + "operationId": "teamRequestDecline", + "summary": "Decline join request", + "description": "Decline someone's request to join your team", + "tags": [ + "Teams" + ], + "security": [ + { + "OAuth2": [ + "team:lead" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "teamId", + "schema": { + "type": "string", + "example": "coders" + }, + "required": true + }, + { + "in": "path", + "name": "userId", + "schema": { + "type": "string", + "example": "neio" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The join request has been declined and is no longer pending.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + } + } + } + }, + "/team/{teamId}/kick/{userId}": { + "post": { + "operationId": "teamIdKickUserId", + "summary": "Kick a user from your team", + "description": "Kick a member out of one of your teams.\n- \n", + "tags": [ + "Teams" + ], + "security": [ + { + "OAuth2": [ + "team:lead" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "teamId", + "schema": { + "type": "string", + "example": "coders" + }, + "required": true + }, + { + "in": "path", + "name": "userId", + "schema": { + "type": "string", + "example": "neio" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The member has been kicked from the team.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + } + } + } + }, + "/team/{teamId}/pm-all": { + "post": { + "operationId": "teamIdPmAll", + "summary": "Message all members", + "description": "Send a private message to all members of a team.\nYou must own the team.\n", + "tags": [ + "Teams" + ], + "security": [ + { + "OAuth2": [ + "team:lead" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "teamId", + "schema": { + "type": "string", + "example": "coders" + }, + "required": true + } + ], + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "message": { + "type": "string", + "description": "The message to send to all your team members." + } + } + } + } + } + }, + "responses": { + "200": { + "description": "The message has successfully been sent to all team members.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "400": { + "description": "The sending of message to all team members has failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/streamer/live": { + "get": { + "operationId": "streamerLive", + "summary": "Get live streamers", + "description": "Get basic info about currently streaming users.\n\nThis API is very fast and cheap on lichess side.\nSo you can call it quite often (like once every 5 seconds).\n", + "tags": [ + "Users" + ], + "security": [], + "responses": { + "200": { + "description": "The list of live streamers and their respective information.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/LightUser" + }, + "example": [ + { + "id": "chess-network", + "name": "Chess-Network", + "title": "NM", + "patron": true, + "stream": { + "service": "twitch", + "status": "Tuesday night 🐴 chess | lichess.org", + "lang": "en" + }, + "streamer": { + "name": "ChessNetwork", + "headline": "Chess with commentary, tournament competition, viewer interaction, and more.", + "description": "I'm a self-taught National Master in chess from Pennsylvania, USA who was introduced to the game by my father in 1988 at age 8. I've been playing since, enjoy teaching, and have been a broadcaster of all things chess since 2011. It's my hope your experience with this stream is both fun and educational. 😎 -Jerry", + "twitch": "https://twitch.tv/chessnetwork", + "youTube": "https://www.youtube.com/channel/UCCDOQrpqLqKVcTCKzqarxLg/live", + "image": "https://image.lichess1.org/display?h=350&op=thumbnail&path=orlandikill:streamer:orlandikill:wiw356Np.jpg&w=350&sig=9912e0c45e42f37e7cd2716af6bd41bb10497b0c" + } + } + ] + } + } + } + } + } + } + }, + "/api/crosstable/{user1}/{user2}": { + "get": { + "operationId": "apiCrosstable", + "summary": "Get crosstable", + "description": "Get total number of games, and current score, of any two users.\n\nIf the `matchup` flag is provided, and the users are currently playing, also gets the current match game number and scores.\n", + "tags": [ + "Users" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "user1", + "schema": { + "type": "string" + }, + "required": true + }, + { + "in": "path", + "name": "user2", + "schema": { + "type": "string" + }, + "required": true + }, + { + "in": "query", + "name": "matchup", + "description": "Whether to get the current match data, if any", + "schema": { + "type": "boolean" + } + } + ], + "responses": { + "200": { + "description": "The crosstable of the two users.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Crosstable" + } + } + } + } + } + } + }, + "/api/player/autocomplete": { + "get": { + "operationId": "apiPlayerAutocomplete", + "summary": "Autocomplete usernames", + "description": "Provides autocompletion options for an incomplete username.\n", + "tags": [ + "Users" + ], + "security": [], + "parameters": [ + { + "in": "query", + "name": "term", + "description": "The beginning of a username", + "schema": { + "type": "string", + "minLength": 3 + }, + "required": true + }, + { + "in": "query", + "name": "object", + "description": "- `false` returns an array of usernames\n- `true` returns an object with matching users\n", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "friend", + "description": "Returns followed players matching `term` if any, else returns other players.\nRequires [OAuth](#tag/OAuth).\n", + "schema": { + "type": "boolean" + } + } + ], + "responses": { + "200": { + "description": "An array of players which usernames start with the provided term.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "type": "array", + "items": { + "type": "string" + } + }, + { + "type": "object", + "properties": { + "result": { + "type": "array", + "items": { + "$ref": "#/components/schemas/LightUserOnline" + } + } + } + } + ] + } + } + } + } + } + } + }, + "/api/rel/following": { + "get": { + "operationId": "apiUserFollowing", + "summary": "Get users followed by the logged in user", + "description": "Users are streamed as [ndjson](#section/Introduction/Streaming-with-ND-JSON).\n", + "tags": [ + "Relations" + ], + "security": [ + { + "OAuth2": [ + "follow:read" + ] + } + ], + "responses": { + "200": { + "description": "The list of users followed by a user.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/x-ndjson": { + "schema": { + "$ref": "#/components/schemas/UserExtended" + } + } + } + } + } + } + }, + "/api/rel/follow/{username}": { + "post": { + "operationId": "followUser", + "summary": "Follow a player", + "description": "Follow a player, adding them to your list of Lichess friends.\n", + "tags": [ + "Relations" + ], + "security": [ + { + "OAuth2": [ + "follow:write" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "username", + "schema": { + "type": "string", + "example": "thibault" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The player was successfully added.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + } + } + } + }, + "/api/rel/unfollow/{username}": { + "post": { + "operationId": "unfollowUser", + "summary": "Unfollow a player", + "description": "Unfollow a player, removing them from your list of Lichess friends.\n", + "tags": [ + "Relations" + ], + "security": [ + { + "OAuth2": [ + "follow:write" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "username", + "schema": { + "type": "string", + "example": "thibault" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The player was successfully removed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + } + } + } + }, + "/api/stream/event": { + "get": { + "operationId": "apiStreamEvent", + "summary": "Stream incoming events", + "description": "\n Stream the events reaching a lichess user in real time as [ndjson](#section/Introduction/Streaming-with-ND-JSON).\n\n An empty line is sent every 6 seconds for keep alive purposes.\n\n Each non-empty line is a JSON object containing a `type` field. Possible values are:\n - `gameStart` Start of a game\n - `gameFinish` Completion of a game\n - `challenge` A player sends you a challenge or you challenge someone\n - `challengeCanceled` A player cancels their challenge to you\n - `challengeDeclined` The opponent declines your challenge\n \n When the stream opens, all current challenges and games are sent.", + "tags": [ + "Board", + "Bot" + ], + "security": [ + { + "OAuth2": [ + "challenge:read", + "bot:play", + "board:play" + ] + } + ], + "responses": { + "200": { + "description": "The stream of events reaching the logged in user.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/x-ndjson": { + "schema": { + "oneOf": [ + { + "$ref": "#/components/schemas/GameStartEvent" + }, + { + "$ref": "#/components/schemas/GameFinishEvent" + }, + { + "$ref": "#/components/schemas/ChallengeEvent" + }, + { + "$ref": "#/components/schemas/ChallengeCanceledEvent" + }, + { + "$ref": "#/components/schemas/ChallengeDeclinedEvent" + } + ] + }, + "examples": { + "challenge": { + "$ref": "#/components/examples/challenge" + }, + "challengeCanceled": { + "$ref": "#/components/examples/challengeCanceled" + }, + "challengeDeclined": { + "$ref": "#/components/examples/challengeDeclined" + }, + "gameStart": { + "$ref": "#/components/examples/gameStart" + }, + "gameFinish": { + "$ref": "#/components/examples/gameFinish" + } + } + } + } + } + } + } + }, + "/api/board/seek": { + "post": { + "operationId": "apiBoardSeek", + "summary": "Create a seek", + "description": "\n Create a public seek, to start a game with a random player.\n\n ### Real-time seek\n\n Specify the `time` and `increment` clock values. The response is streamed but doesn't contain any information.\n\n **Keep the connection open to keep the seek active**.\n\n If the client closes the connection, the seek is canceled. This way, if the client terminates, the user won't be paired in a game they wouldn't play.\n When the seek is accepted, or expires, the server closes the connection.\n\n **Make sure to also have an [Event stream](#operation/apiStreamEvent) open**, to be notified when a game starts.\n We recommend opening the [Event stream](#operation/apiStreamEvent) first, then the seek stream. This way,\n you won't miss the game event if the seek is accepted immediately.\n\n ### Correspondence seek\n\n Specify the `days` per turn value. The response is not streamed, it immediately completes with the seek ID. The seek remains active on the server until it is joined by someone.", + "tags": [ + "Board" + ], + "security": [ + { + "OAuth2": [ + "board:play" + ] + } + ], + "requestBody": { + "description": "Parameters of the seek", + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "rated": { + "type": "boolean", + "description": "Whether the game is rated and impacts players ratings.", + "example": true, + "default": false + }, + "time": { + "type": "number", + "description": "Clock initial time in minutes. Required for real-time seeks.", + "example": 15, + "minimum": 0, + "maximum": 180 + }, + "increment": { + "type": "integer", + "description": "Clock increment in seconds. Required for real-time seeks.", + "example": 15, + "minimum": 0, + "maximum": 180 + }, + "days": { + "type": "integer", + "description": "Days per turn. Required for correspondence seeks.", + "enum": [ + 1, + 2, + 3, + 5, + 7, + 10, + 14 + ] + }, + "variant": { + "$ref": "#/components/schemas/VariantKey" + }, + "color": { + "type": "string", + "description": "The color to play. Better left empty to automatically get 50% white.", + "enum": [ + "random", + "white", + "black" + ], + "default": "random" + }, + "ratingRange": { + "type": "string", + "description": "The rating range of potential opponents. Better left empty.\nExample: 1500-1800\n" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "The seek was successfully created.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "text/plain": { + "example": "" + } + } + }, + "400": { + "description": "The creation of the seek failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/board/game/stream/{gameId}": { + "get": { + "operationId": "boardGameStream", + "summary": "Stream Board game state", + "description": " Stream the state of a game being played with the Board API, as [ndjson](#section/Introduction/Streaming-with-ND-JSON).\n\nUse this endpoint to get updates about the game in real-time, with a single request.\n\nEach line is a JSON object containing a `type` field. Possible values are:\n - `gameFull` Full game data. All values are immutable, except for the `state` field.\n - `gameState` Current state of the game. Immutable values not included. Sent when a move is played, a draw is offered, or when the game ends.\n - `chatLine` Chat message sent by a user in the `room` \"player\" or \"spectator\".\n\n - `opponentGone` Whether the opponent has left the game, and how long before you can claim a win or draw.\n\n \nThe first line is always of type `gameFull`.\n\n \nThe server closes the stream when the game ends, or if the game has already ended.", + "tags": [ + "Board" + ], + "security": [ + { + "OAuth2": [ + "board:play" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "gameId", + "schema": { + "type": "string", + "example": "5IrD6Gzz" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The stream of the game.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/x-ndjson": { + "schema": { + "oneOf": [ + { + "$ref": "#/components/schemas/GameFullEvent" + }, + { + "$ref": "#/components/schemas/GameStateEvent" + }, + { + "$ref": "#/components/schemas/ChatLineEvent" + }, + { + "$ref": "#/components/schemas/OpponentGone" + } + ] + }, + "examples": { + "gameFull": { + "$ref": "#/components/examples/gameFull" + }, + "gameState": { + "$ref": "#/components/examples/gameState" + }, + "chatLine": { + "$ref": "#/components/examples/chatLine" + }, + "chatLineSpectator": { + "$ref": "#/components/examples/chatLineSpectator" + }, + "opponentGoneTrue": { + "$ref": "#/components/examples/opponentGoneTrue" + }, + "opponentGoneFalse": { + "$ref": "#/components/examples/opponentGoneFalse" + }, + "gameStateResign": { + "$ref": "#/components/examples/gameStateResign" + } + } + } + } + }, + "404": { + "description": "The game was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotFound" + } + } + } + } + } + } + }, + "/api/board/game/{gameId}/move/{move}": { + "post": { + "operationId": "boardGameMove", + "summary": "Make a Board move", + "description": "Make a move in a game being played with the Board API.\n\nThe move can also contain a draw offer/agreement.\n", + "tags": [ + "Board" + ], + "security": [ + { + "OAuth2": [ + "board:play" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "gameId", + "schema": { + "type": "string", + "example": "5IrD6Gzz" + }, + "required": true + }, + { + "in": "path", + "name": "move", + "required": true, + "description": "The move to play, in UCI format", + "schema": { + "type": "string", + "example": "e2e4" + } + }, + { + "in": "query", + "name": "offeringDraw", + "description": "Whether to offer (or agree to) a draw", + "schema": { + "type": "boolean" + } + } + ], + "responses": { + "200": { + "description": "The move was successfully made.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "400": { + "description": "The move failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/board/game/{gameId}/chat": { + "parameters": [ + { + "in": "path", + "name": "gameId", + "schema": { + "type": "string", + "example": "5IrD6Gzz" + }, + "required": true + } + ], + "post": { + "operationId": "boardGameChatPost", + "summary": "Write in the chat", + "description": "Post a message to the player or spectator chat, in a game being played with the Board API.\n", + "tags": [ + "Board" + ], + "security": [ + { + "OAuth2": [ + "board:play" + ] + } + ], + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "room": { + "type": "string", + "enum": [ + "player", + "spectator" + ] + }, + "text": { + "type": "string", + "example": "Thank you for the game!" + } + }, + "required": [ + "room", + "text" + ] + } + } + } + }, + "responses": { + "200": { + "description": "The message was successfully posted in the chat.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "400": { + "description": "The posting of the message in the chat failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + }, + "get": { + "operationId": "boardGameChatGet", + "summary": "Fetch the game chat", + "description": "Get the messages posted in the game chat\n", + "tags": [ + "Board" + ], + "security": [ + { + "OAuth2": [ + "board:play" + ] + } + ], + "responses": { + "200": { + "description": "The messages posted in the chat.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/x-ndjson": { + "schema": { + "$ref": "#/components/schemas/GameChat" + } + } + } + } + } + } + }, + "/api/board/game/{gameId}/abort": { + "post": { + "operationId": "boardGameAbort", + "summary": "Abort a game", + "description": "Abort a game being played with the Board API.\n", + "tags": [ + "Board" + ], + "security": [ + { + "OAuth2": [ + "board:play" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "gameId", + "schema": { + "type": "string", + "example": "5IrD6Gzz" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The game successfully aborted.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "400": { + "description": "The abortion of the game failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/board/game/{gameId}/resign": { + "post": { + "operationId": "boardGameResign", + "summary": "Resign a game", + "description": "Resign a game being played with the Board API.\n", + "tags": [ + "Board" + ], + "security": [ + { + "OAuth2": [ + "board:play" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "gameId", + "schema": { + "type": "string", + "example": "5IrD6Gzz" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The game was successfully resigned.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "400": { + "description": "The resigning from the game failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/board/game/{gameId}/draw/{accept}": { + "post": { + "operationId": "boardGameDraw", + "summary": "Handle draw offers", + "description": "Create/accept/decline draw offers.\n- `yes`: Offer a draw, or accept the opponent's draw offer.\n- `no`: Decline a draw offer from the opponent.\n", + "tags": [ + "Board" + ], + "security": [ + { + "OAuth2": [ + "board:play" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "gameId", + "schema": { + "type": "string", + "example": "5IrD6Gzz" + }, + "required": true + }, + { + "in": "path", + "name": "accept", + "schema": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "const": "yes" + } + ], + "example": "yes" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The draw offer was successfully sent.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "400": { + "description": "The draw offering failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/board/game/{gameId}/takeback/{accept}": { + "post": { + "operationId": "boardGameTakeback", + "summary": "Handle takeback offers", + "description": "Create/accept/decline takebacks.\n- `yes`: Propose a takeback, or accept the opponent's takeback offer.\n- `no`: Decline a takeback offer from the opponent.\n", + "tags": [ + "Board" + ], + "security": [ + { + "OAuth2": [ + "board:play" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "gameId", + "schema": { + "type": "string", + "example": "5IrD6Gzz" + }, + "required": true + }, + { + "in": "path", + "name": "accept", + "schema": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "const": "yes" + } + ], + "example": "yes" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The takeback offer was successfully sent.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "400": { + "description": "The takeback offering failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/board/game/{gameId}/claim-victory": { + "post": { + "operationId": "boardGameClaimVictory", + "summary": "Claim victory of a game", + "description": "Claim victory when the opponent has left the game for a while.\n", + "tags": [ + "Board" + ], + "security": [ + { + "OAuth2": [ + "board:play" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "gameId", + "schema": { + "type": "string", + "example": "5IrD6Gzz" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The victory was successfully claimed.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "400": { + "description": "The victory claim has failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/board/game/{gameId}/berserk": { + "post": { + "operationId": "boardGameBerserk", + "summary": "Berserk a tournament game", + "description": "Go berserk on an arena tournament game. Halves the clock time, grants an extra point upon winning.\nOnly available in arena tournaments that allow berserk, and before each player has made a move.\n", + "tags": [ + "Board" + ], + "security": [ + { + "OAuth2": [ + "board:play" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "gameId", + "schema": { + "type": "string", + "example": "5IrD6Gzz" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The player successfully whent berserk.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "400": { + "description": "The berserk has failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/bot/online": { + "get": { + "operationId": "apiBotOnline", + "summary": "Get online bots", + "tags": [ + "Bot" + ], + "security": [], + "description": "Stream the [online bot users](https://lichess.org/player/bots), as [ndjson](#section/Introduction/Streaming-with-ND-JSON). Throttled to 50 bot users per second.", + "parameters": [ + { + "in": "query", + "name": "nb", + "description": "How many bot users to fetch", + "schema": { + "type": "integer", + "minimum": 1, + "example": 20 + } + } + ], + "responses": { + "200": { + "description": "The list of online bot users", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/x-ndjson": { + "schema": { + "$ref": "#/components/schemas/User" + } + } + } + } + } + } + }, + "/api/bot/account/upgrade": { + "post": { + "operationId": "botAccountUpgrade", + "summary": "Upgrade to Bot account", + "description": "Upgrade a lichess player account into a Bot account. Only Bot accounts can use the Bot API.\n\nThe account **cannot have played any game** before becoming a Bot account. The upgrade is **irreversible**. The account will only be able to play as a Bot.\n\nTo upgrade an account to Bot, use the [official lichess-bot client](https://github.com/ShailChoksi/lichess-bot), or follow these steps:\n- Create an [API access token](https://lichess.org/account/oauth/token/create?scopes[]=bot:play) with \"Play bot moves\" permission.\n- `curl -d '' https://lichess.org/api/bot/account/upgrade -H \"Authorization: Bearer \"`\n\nTo know if an account has already been upgraded, use the [Get my profile API](#operation/accountMe):\nthe `title` field should be set to `BOT`.\n", + "tags": [ + "Bot" + ], + "security": [ + { + "OAuth2": [ + "bot:play" + ] + } + ], + "responses": { + "200": { + "description": "The bot account was successfully upgraded.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "400": { + "description": "The upgrade of the bot account failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/bot/game/stream/{gameId}": { + "get": { + "operationId": "botGameStream", + "summary": "Stream Bot game state", + "description": " Stream the state of a game being played with the Bot API, as [ndjson](#section/Introduction/Streaming-with-ND-JSON).\n\nUse this endpoint to get updates about the game in real-time, with a single request.\n\nEach line is a JSON object containing a `type` field. Possible values are:\n - `gameFull` Full game data. All values are immutable, except for the `state` field.\n - `gameState` Current state of the game. Immutable values not included.\n - `chatLine` Chat message sent by a user (or the bot itself) in the `room` \"player\" or \"spectator\".\n\n - `opponentGone` Whether the opponent has left the game, and how long before you can claim a win or draw.\n\n \nThe first line is always of type `gameFull`.", + "tags": [ + "Bot" + ], + "security": [ + { + "OAuth2": [ + "bot:play" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "gameId", + "schema": { + "type": "string", + "example": "5IrD6Gzz" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The stream of the bot game.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/x-ndjson": { + "schema": { + "oneOf": [ + { + "$ref": "#/components/schemas/GameFullEvent" + }, + { + "$ref": "#/components/schemas/GameStateEvent" + }, + { + "$ref": "#/components/schemas/ChatLineEvent" + }, + { + "$ref": "#/components/schemas/OpponentGone" + } + ] + }, + "examples": { + "gameFull": { + "$ref": "#/components/examples/gameFull" + }, + "gameState": { + "$ref": "#/components/examples/gameState" + }, + "chatLine": { + "$ref": "#/components/examples/chatLine" + }, + "chatLineSpectator": { + "$ref": "#/components/examples/chatLineSpectator" + }, + "opponentGoneTrue": { + "$ref": "#/components/examples/opponentGoneTrue" + }, + "opponentGoneFalse": { + "$ref": "#/components/examples/opponentGoneFalse" + }, + "gameStateResign": { + "$ref": "#/components/examples/gameStateResign" + } + } + } + } + }, + "404": { + "description": "The bot game was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotFound" + } + } + } + } + } + } + }, + "/api/bot/game/{gameId}/move/{move}": { + "post": { + "operationId": "botGameMove", + "summary": "Make a Bot move", + "description": "Make a move in a game being played with the Bot API.\n\nThe move can also contain a draw offer/agreement.\n", + "tags": [ + "Bot" + ], + "security": [ + { + "OAuth2": [ + "bot:play" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "gameId", + "schema": { + "type": "string", + "example": "5IrD6Gzz" + }, + "required": true + }, + { + "in": "path", + "name": "move", + "required": true, + "description": "The move to play, in UCI format", + "schema": { + "type": "string", + "example": "e2e4" + } + }, + { + "in": "query", + "name": "offeringDraw", + "description": "Whether to offer (or agree to) a draw", + "schema": { + "type": "boolean" + } + } + ], + "responses": { + "200": { + "description": "The bot move was successfully made.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "400": { + "description": "The bot move failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/bot/game/{gameId}/chat": { + "post": { + "operationId": "botGameChat", + "summary": "Write in the chat", + "description": "Post a message to the player or spectator chat, in a game being played with the Bot API.\n", + "tags": [ + "Bot" + ], + "security": [ + { + "OAuth2": [ + "bot:play" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "gameId", + "schema": { + "type": "string", + "example": "5IrD6Gzz" + }, + "required": true + } + ], + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "room": { + "type": "string", + "enum": [ + "player", + "spectator" + ] + }, + "text": { + "type": "string", + "example": "Thank you for the game!" + } + }, + "required": [ + "room", + "text" + ] + } + } + } + }, + "responses": { + "200": { + "description": "The message was successfully posted in chat.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "400": { + "description": "The posting of the message in chat failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + }, + "get": { + "operationId": "botGameChatGet", + "summary": "Fetch the game chat", + "description": "Get the messages posted in the game chat\n", + "tags": [ + "Bot" + ], + "security": [ + { + "OAuth2": [ + "bot:play" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "gameId", + "schema": { + "type": "string", + "example": "5IrD6Gzz" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The messages posted in the chat.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/x-ndjson": { + "schema": { + "$ref": "#/components/schemas/GameChat" + } + } + } + } + } + } + }, + "/api/bot/game/{gameId}/abort": { + "post": { + "operationId": "botGameAbort", + "summary": "Abort a game", + "description": "Abort a game being played with the Bot API.\n", + "tags": [ + "Bot" + ], + "security": [ + { + "OAuth2": [ + "bot:play" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "gameId", + "schema": { + "type": "string", + "example": "5IrD6Gzz" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The game was successfully aborted.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "400": { + "description": "The abortion of the game failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/bot/game/{gameId}/resign": { + "post": { + "operationId": "botGameResign", + "summary": "Resign a game", + "description": "Resign a game being played with the Bot API.\n", + "tags": [ + "Bot" + ], + "security": [ + { + "OAuth2": [ + "bot:play" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "gameId", + "schema": { + "type": "string", + "example": "5IrD6Gzz" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The game was successfully resigned from.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "400": { + "description": "Resigning the game failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/challenge": { + "get": { + "operationId": "challengeList", + "summary": "List your challenges", + "description": "Get a list of challenges created by or targeted at you.\n", + "tags": [ + "Challenges" + ], + "security": [ + { + "OAuth2": [ + "challenge:read" + ] + } + ], + "responses": { + "200": { + "description": "The list of challenges created by or targeted at the logged in user.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "in": { + "type": "array", + "description": "Incoming challenges i.e. targeted at you", + "items": { + "$ref": "#/components/schemas/ChallengeJson" + } + }, + "out": { + "type": "array", + "description": "Outgoing challenges i.e. created by you", + "items": { + "$ref": "#/components/schemas/ChallengeJson" + } + } + } + } + } + } + } + } + } + }, + "/api/challenge/{username}": { + "post": { + "operationId": "challengeCreate", + "summary": "Create a challenge", + "description": "Challenge someone to play. The targeted player can choose to accept or decline.\n\nIf the challenge is accepted, you will be notified on the [event stream](#operation/apiStreamEvent)\nthat a new game has started. The game ID will be the same as the challenge ID.\n\nIf you also have an OAuth token with `challenge:write` scope for the receiving user,\nyou can make them accept the challenge immediately by setting the `acceptByToken` field.\n\nChallenges for realtime games (not correspondence) expire after 20s if not accepted.\nTo prevent that, use the `keepAliveStream` flag described below.\n", + "tags": [ + "Challenges" + ], + "security": [ + { + "OAuth2": [ + "challenge:write", + "bot:play", + "board:play" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "username", + "schema": { + "type": "string", + "example": "LeelaChess" + }, + "required": true + } + ], + "requestBody": { + "description": "Parameters of the challenge", + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "rated": { + "type": "boolean", + "description": "Game is rated and impacts players ratings", + "default": false + }, + "clock.limit": { + "type": "number", + "description": "Clock initial time in seconds. If empty, a correspondence game is created.", + "example": 300, + "minimum": 0, + "maximum": 10800 + }, + "clock.increment": { + "type": "integer", + "description": "Clock increment in seconds. If empty, a correspondence game is created.", + "example": 1, + "minimum": 0, + "maximum": 60 + }, + "days": { + "type": "integer", + "description": "Days per move, for correspondence games. Clock settings must be omitted.", + "enum": [ + 1, + 2, + 3, + 5, + 7, + 10, + 14 + ] + }, + "color": { + "type": "string", + "description": "Which color you get to play", + "enum": [ + "random", + "white", + "black" + ], + "default": "random" + }, + "variant": { + "$ref": "#/components/schemas/VariantKey" + }, + "fen": { + "$ref": "#/components/schemas/FromPositionFEN" + }, + "keepAliveStream": { + "type": "boolean", + "description": "If set, the response is streamed as [ndjson](#section/Introduction/Streaming-with-ND-JSON).\nThe challenge is kept alive until the connection is closed by the client.\nWhen the challenge is accepted, declined or canceled, a message of the form `{\"done\":\"accepted\"}` is sent,\nthen the connection is closed by the server.\nIf not set, the response is not streamed, and the challenge expires after 20s if not accepted.\n" + }, + "acceptByToken": { + "type": "string", + "description": "Immediately accept the challenge and create the game.\nPass in an OAuth token (with the `challenge:write` scope) for the receiving user.\nOn success, the response will contain a `game` field instead of a `challenge` field.\n\nAlternatively, consider the [bulk pairing API](#operation/bulkPairingCreate).\n" + }, + "message": { + "type": "string", + "description": "**Only if `acceptByToken` is set.**\n\nMessage that is sent to each player, when the game is created. It is sent from your user account.\n\n`{opponent}`, `{player}` and `{game}` are placeholders that will be replaced with the opponent name, player name, and the game URLs.\n\nYou can omit this field to send the default message,\nbut if you set your own message, it must at least contain the `{game}` placeholder.\n", + "default": "Your game with {opponent} is ready: {game}." + }, + "rules": { + "type": "string", + "enum": [ + "noAbort", + "noRematch", + "noGiveTime", + "noClaimWin" + ], + "description": "Extra game rules separated by commas.\nExample: `noAbort,noRematch`\n" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "The challenge was successfully created.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChallengeJson" + } + } + } + }, + "400": { + "description": "The creation of the challenge failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/challenge/{challengeId}/accept": { + "post": { + "operationId": "challengeAccept", + "summary": "Accept a challenge", + "description": "Accept an incoming challenge.\n\nYou should receive a `gameStart` event on the [incoming events stream](#operation/apiStreamEvent).\n", + "tags": [ + "Challenges" + ], + "security": [ + { + "OAuth2": [ + "challenge:write", + "bot:play", + "board:play" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "challengeId", + "schema": { + "type": "string", + "example": "5IrD6Gzz" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The challenge was successfully accepted.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "404": { + "description": "The challenge to accept was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotFound" + } + } + } + } + } + } + }, + "/api/challenge/{challengeId}/decline": { + "post": { + "operationId": "challengeDecline", + "summary": "Decline a challenge", + "description": "Decline an incoming challenge.\n", + "tags": [ + "Challenges" + ], + "security": [ + { + "OAuth2": [ + "challenge:write", + "bot:play", + "board:play" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "challengeId", + "schema": { + "type": "string", + "example": "5IrD6Gzz" + }, + "required": true + } + ], + "requestBody": { + "description": "Details related to decline of challenge", + "required": false, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "reason": { + "type": "string", + "description": "Reason challenge was declined. It will be translated to the player's language. See [the full list in the translation file](https://github.com/ornicar/lila/blob/master/translation/source/challenge.xml#L14).", + "enum": [ + "generic", + "later", + "tooFast", + "tooSlow", + "timeControl", + "rated", + "casual", + "standard", + "variant", + "noBot", + "onlyBot" + ] + } + } + } + } + } + }, + "responses": { + "200": { + "description": "The challenge was successfully declined.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "404": { + "description": "The challenge to decline was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotFound" + } + } + } + } + } + } + }, + "/api/challenge/{challengeId}/cancel": { + "post": { + "operationId": "challengeCancel", + "summary": "Cancel a challenge", + "description": "Cancel a challenge you sent, or aborts the game if the challenge was accepted, but the game was not yet played.\nNote that the ID of a game is the same as the ID of the challenge that created it.\n\nWorks for user challenges and open challenges alike.\n", + "tags": [ + "Challenges" + ], + "security": [ + { + "OAuth2": [ + "challenge:write", + "bot:play", + "board:play" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "challengeId", + "schema": { + "type": "string", + "example": "5IrD6Gzz" + }, + "required": true + }, + { + "in": "query", + "name": "opponentToken", + "description": "Optional `challenge:write` token of the opponent. If set, the game can be canceled even if both players have moved.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The challenge was successfully cancelled.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "404": { + "description": "The challenge to cancel was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotFound" + } + } + } + } + } + } + }, + "/api/challenge/ai": { + "post": { + "operationId": "challengeAi", + "summary": "Challenge the AI", + "description": "Start a game with Lichess AI.\n\nYou will be notified on the [event stream](#operation/apiStreamEvent) that a new game has started.\n", + "tags": [ + "Challenges" + ], + "security": [ + { + "OAuth2": [ + "challenge:write", + "bot:play", + "board:play" + ] + } + ], + "requestBody": { + "description": "Parameters of the game", + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "level": { + "type": "number", + "description": "AI strength", + "minimum": 1, + "maximum": 8 + }, + "clock.limit": { + "type": "number", + "description": "Clock initial time in seconds. If empty, a correspondence game is created.", + "example": 300, + "minimum": 0, + "maximum": 10800 + }, + "clock.increment": { + "type": "integer", + "description": "Clock increment in seconds. If empty, a correspondence game is created.", + "example": 1, + "minimum": 0, + "maximum": 60 + }, + "days": { + "type": "integer", + "description": "Days per move, for correspondence games. Clock settings must be omitted.", + "enum": [ + 1, + 2, + 3, + 5, + 7, + 10, + 14 + ] + }, + "color": { + "type": "string", + "description": "Which color you get to play", + "enum": [ + "random", + "white", + "black" + ], + "default": "random" + }, + "variant": { + "$ref": "#/components/schemas/VariantKey" + }, + "fen": { + "$ref": "#/components/schemas/FromPositionFEN" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "The game with Lichess AI was successfully started.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GameJson" + } + } + } + }, + "400": { + "description": "The creation of a game with Lichess AI failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/challenge/open": { + "post": { + "operationId": "challengeOpen", + "summary": "Open-ended challenge", + "description": "Create a challenge that any 2 players can join.\n\nShare the URL of the challenge. the first 2 players to click it will be paired for a game.\n\nThe response body also contains `whiteUrl` and `blackUrl`.\nYou can control which color each player gets by giving them these URLs,\ninstead of the main challenge URL.\n\nOpen challenges expire after 24h.\n\nIf the challenge creation is [authenticated with OAuth2](#section/Introduction/Authentication),\nthen you can use the [challenge cancel endpoint](#operation/challengeCancel) to cancel it.\n\nTo directly pair 2 known players, use [this endpoint](#operation/challengeCreate) instead,\nwith the `acceptByToken` parameter.\n", + "tags": [ + "Challenges" + ], + "security": [], + "requestBody": { + "description": "Parameters of the game", + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "rated": { + "type": "boolean", + "description": "Game is rated and impacts players ratings", + "default": false + }, + "clock.limit": { + "type": "number", + "description": "Clock initial time in seconds. If empty, a correspondence game is created.", + "example": 300, + "minimum": 0, + "maximum": 10800 + }, + "clock.increment": { + "type": "integer", + "description": "Clock increment in seconds. If empty, a correspondence game is created.", + "example": 1, + "minimum": 0, + "maximum": 60 + }, + "days": { + "type": "integer", + "description": "Days per turn. For correspondence challenges.", + "enum": [ + 1, + 2, + 3, + 5, + 7, + 10, + 14 + ] + }, + "variant": { + "$ref": "#/components/schemas/VariantKey" + }, + "fen": { + "$ref": "#/components/schemas/FromPositionFEN" + }, + "name": { + "type": "string", + "description": "Optional name for the challenge, that players will see on the challenge page." + }, + "rules": { + "type": "string", + "enum": [ + "noAbort", + "noRematch", + "noGiveTime", + "noClaimWin" + ], + "description": "Extra game rules separated by commas.\nExample: `noAbort,noRematch`\n" + }, + "users": { + "type": "string", + "description": "Optional pair of usernames, separated by a comma.\nIf set, only these users will be allowed to join the game.\nThe first username gets the white pieces.\nExample: `Username1,Username2`\n" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "The challenge was successfully created.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChallengeOpenJson" + } + } + } + }, + "400": { + "description": "The creation of the challenge failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/challenge/{gameId}/start-clocks": { + "post": { + "operationId": "challengeStartClocks", + "summary": "Start clocks of a game", + "description": "Start the clocks of a game immediately, even if a player has not yet made a move.\n\nRequires the OAuth tokens of both players with `challenge:write` scope.\n\nIf the clocks have already started, the call will have no effect.\n", + "tags": [ + "Challenges" + ], + "security": [ + { + "OAuth2": [ + "challenge:write" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "gameId", + "schema": { + "type": "string", + "description": "ID of the game" + }, + "required": true + }, + { + "in": "query", + "name": "token1", + "description": "OAuth token of a player", + "schema": { + "type": "string" + } + }, + { + "in": "query", + "name": "token2", + "description": "OAuth token of the other player", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The clock of a game was successfully started.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + } + } + } + }, + "/api/bulk-pairing": { + "get": { + "operationId": "bulkPairingGet", + "summary": "View upcoming bulk pairings", + "description": "Get a list of upcoming bulk pairings you created.\n\nOnly bulk pairings that are scheduled in the future, or that have a clock start scheduled in the future, are listed.\n\nBulk pairings are deleted from the server after the pairings are done and the clocks have started.\n", + "tags": [ + "Bulk pairings" + ], + "security": [ + { + "OAuth2": [ + "challenge:bulk" + ] + } + ], + "responses": { + "200": { + "description": "The list of upcoming bulk pairing the logged in user created.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/BulkPairing" + } + } + } + } + } + } + }, + "post": { + "operationId": "bulkPairingCreate", + "summary": "Create a bulk pairing", + "description": "Schedule many games at once, up to 24h in advance.\n\nOAuth tokens are required for all paired players, with the `challenge:write` scope.\n\nYou can schedule up to 500 games every 10 minutes. [Contact us](mailto:contact@lichess.org) if you need higher limits.\n\nIf games have a real-time clock, each player must have only one pairing.\nFor correspondence games, players can have multiple pairings within the same bulk.\n\nThe entire bulk is rejected if:\n - a token is missing\n - a token is present more than once (except in correspondence)\n - a token lacks the `challenge:write` scope\n - a player account is closed\n - a player is paired more than once (except in correspondence)\n - a bulk is already scheduled to start at the same time with the same player\n - you have 10 scheduled bulks\n - you have 1000 scheduled games\n\nPartial bulks are never created. Either it all fails, or it all succeeds.\nWhen it fails, it does so with an error message explaining the issue.\nFailed bulks are not counted in the rate limiting, they are free.\nFix the issues, manually or programmatically, then retry to schedule the bulk.\n\nA successful bulk creation returns a JSON bulk document. Its ID can be used for further operations.\n", + "tags": [ + "Bulk pairings" + ], + "security": [ + { + "OAuth2": [ + "challenge:bulk" + ] + } + ], + "requestBody": { + "description": "Parameters of the pairings", + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "players": { + "type": "string", + "description": "OAuth tokens of all the players to pair, with the syntax `tokenOfWhitePlayerInGame1:tokenOfBlackPlayerInGame1,tokenOfWhitePlayerInGame2:tokenOfBlackPlayerInGame2,...`.\n\nThe 2 tokens of the players of a game are separated with `:`. The first token gets the white pieces. Games are separated with `,`.\n\nUp to 1000 tokens can be sent, for a max of 500 games.\n\nEach token must be included at most once.\n\nExample: `token1:token2,token3:token4,token5:token6`\n" + }, + "clock.limit": { + "type": "number", + "description": "Clock initial time in seconds. Example: `600`\n", + "minimum": 0, + "maximum": 10800 + }, + "clock.increment": { + "type": "integer", + "description": "Clock increment in seconds. Example: `2`\n", + "minimum": 0, + "maximum": 60 + }, + "days": { + "type": "integer", + "description": "Days per turn. For correspondence games only.", + "enum": [ + 1, + 2, + 3, + 5, + 7, + 10, + 14 + ] + }, + "pairAt": { + "description": "Date at which the games will be created as a Unix timestamp in milliseconds.\nUp to 24h in the future.\nOmit, or set to current date and time, to start the games immediately.\nExample: `1612289869919`\n", + "type": "integer" + }, + "startClocksAt": { + "description": "Date at which the clocks will be automatically started as a Unix timestamp in milliseconds.\nUp to 24h in the future.\nNote that the clocks can start earlier than specified, if players start making moves in the game.\nIf omitted, the clocks will not start automatically.\nExample: `1612289869919`\n", + "type": "integer" + }, + "rated": { + "type": "boolean", + "description": "Game is rated and impacts players ratings", + "default": false + }, + "variant": { + "$ref": "#/components/schemas/VariantKey" + }, + "fen": { + "$ref": "#/components/schemas/FromPositionFEN" + }, + "message": { + "type": "string", + "description": "Message that will be sent to each player, when the game is created. It is sent from your user account.\n\n`{opponent}` and `{game}` are placeholders that will be replaced with the opponent and the game URLs.\n\nYou can omit this field to send the default message,\nbut if you set your own message, it must at least contain the `{game}` placeholder.\n", + "default": "Your game with {opponent} is ready: {game}." + }, + "rules": { + "type": "string", + "enum": [ + "noAbort", + "noRematch", + "noGiveTime", + "noClaimWin" + ], + "description": "Extra game rules separated by commas.\nExample: `noAbort,noRematch`\n" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "The bulk pairings have been successfully created.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BulkPairing" + } + } + } + }, + "400": { + "description": "The creation of the bulk pairings failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/bulk-pairing/{id}/start-clocks": { + "post": { + "operationId": "bulkPairingStartClocks", + "summary": "Manually start clocks", + "description": "Immediately start all clocks of the games of a bulk pairing.\n\nThis overrides the `startClocksAt` value of an existing bulk pairing.\n\nIf the games have not yet been created (`bulk.pairAt` is in the future), then this does nothing.\n\nIf the clocks have already started (`bulk.startClocksAt` is in the past), then this does nothing.\n", + "tags": [ + "Bulk pairings" + ], + "security": [ + { + "OAuth2": [ + "challenge:bulk" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "id", + "schema": { + "type": "string", + "description": "The ID of the bulk pairing", + "example": "5IrD6Gzz" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The clocks of the games of a bulk pairing were successfully started.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "404": { + "description": "The bulk pairing was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotFound" + } + } + } + } + } + } + }, + "/api/bulk-pairing/{id}": { + "delete": { + "operationId": "bulkPairingDelete", + "summary": "Cancel a bulk pairing", + "description": "Cancel and delete a bulk pairing that is scheduled in the future.\n\nIf the games have already been created, then this does nothing.\n\nCanceling a bulk pairing does not refund the rate limit cost of that bulk pairing.\n", + "tags": [ + "Bulk pairings" + ], + "security": [ + { + "OAuth2": [ + "challenge:bulk" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "id", + "schema": { + "type": "string", + "description": "The ID of the bulk pairing", + "example": "5IrD6Gzz" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The bulk pairing was successfully deleted.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "404": { + "description": "The bulk pairing to delete was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotFound" + } + } + } + } + } + } + }, + "/api/round/{gameId}/add-time/{seconds}": { + "post": { + "operationId": "roundAddTime", + "summary": "Add time to the opponent clock", + "description": "Add seconds to the opponent's clock. Can be used to create games with time odds.\n", + "tags": [ + "Challenges" + ], + "security": [ + { + "OAuth2": [ + "challenge:write" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "gameId", + "schema": { + "type": "string", + "description": "ID of the game" + }, + "required": true + }, + { + "in": "path", + "name": "seconds", + "description": "How many seconds to give", + "schema": { + "type": "string", + "minimum": 1, + "maximum": 86400 + }, + "required": true + } + ], + "responses": { + "200": { + "description": "Time was successfully added to the opponent's clock.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + } + } + } + }, + "/api/token/admin-challenge": { + "post": { + "operationId": "adminChallengeTokens", + "summary": "Admin challenge tokens", + "description": "**This endpoint can only be used by Lichess administrators. It will not work if you do not have the appropriate permissions.** Tournament organizers should instead use [OAuth](#tag/OAuth) to obtain `challenge:write` tokens from users in order to perform bulk pairing.*\n\nCreate and obtain `challenge:write` tokens for multiple users.\n\nIf a similar token already exists for a user, it is reused. This endpoint is idempotent.\n", + "tags": [ + "Challenges" + ], + "security": [ + { + "OAuth2": [ + "web:mod" + ] + } + ], + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "users": { + "description": "Usernames separated with commas", + "type": "string", + "example": "thibault,neio,lizen2,lizen3" + }, + "description": { + "description": "User visible description of the token", + "type": "string", + "example": "FIDE tournament XYZ" + } + }, + "required": [ + "users", + "description" + ] + } + } + } + }, + "responses": { + "200": { + "description": "The `challenge:write` tokens of each user", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "example": { + "thibault": "lLOEkpH58W599xH9", + "neio": "nAYTIJphwWFwKmKk", + "lizen2": "1cnHhuWKHROgiPC4", + "lizen3": "SszJ9Sj1bto0UQCK" + } + } + } + }, + "400": { + "description": "The creation of the tokens failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/inbox/{username}": { + "post": { + "operationId": "inboxUsername", + "summary": "Send a private message", + "description": "Send a private message to another player.\n", + "tags": [ + "Messaging" + ], + "security": [ + { + "OAuth2": [ + "msg:write" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "username", + "schema": { + "type": "string", + "example": "someplayer" + }, + "required": true + } + ], + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "text": { + "type": "string", + "example": "Thank you for the game!" + } + }, + "required": [ + "text" + ] + } + } + } + }, + "responses": { + "200": { + "description": "The private message has been successfully sent.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "400": { + "description": "The sending of the private message has failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/cloud-eval": { + "get": { + "operationId": "apiCloudEval", + "summary": "Get cloud evaluation of a position.", + "description": "Get the cached evaluation of a position, if available.\n\nOpening positions have more chances of being available. There are about 15 million positions in the database.\n\nUp to 5 variations may be available. Variants are supported.\n", + "tags": [ + "Analysis" + ], + "security": [], + "parameters": [ + { + "in": "query", + "name": "fen", + "required": true, + "description": "FEN of the position", + "schema": { + "type": "string" + }, + "example": "rnbqkbnr/ppp1pppp/8/3pP3/8/8/PPPP1PPP/RNBQKBNR b KQkq - 0 2" + }, + { + "in": "query", + "name": "multiPv", + "description": "Number of variations", + "schema": { + "type": "number", + "default": 1 + } + }, + { + "in": "query", + "name": "variant", + "description": "Variant", + "schema": { + "$ref": "#/components/schemas/VariantKey" + } + } + ], + "responses": { + "200": { + "description": "The evaluation of the position.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "example": { + "fen": "rnbqkbnr/ppp1pppp/8/3pP3/8/8/PPPP1PPP/RNBQKBNR b KQkq - 0 2", + "knodes": 13683, + "depth": 22, + "pvs": [ + { + "moves": "c8f5 d2d4 e7e6 g1f3 g8e7 c1e3 c7c5 d4c5 e7c6 b1c3", + "cp": -13 + }, + { + "moves": "c7c5 c2c3 d5d4 g1f3 b8c6 c3d4 c6d4 b1c3 c8d7 f1d3", + "cp": -1 + }, + { + "moves": "e7e6 d2d4 c7c5 c2c3 b8c6 g1f3 c8d7 b1a3 c5d4 c3d4", + "cp": 24 + } + ] + } + } + } + } + } + } + }, + "/api/external-engine": { + "get": { + "operationId": "apiExternalEngineList", + "summary": "List external engines", + "tags": [ + "External engine" + ], + "security": [ + { + "OAuth2": [ + "engine:read" + ] + } + ], + "description": "Lists all external engines that have been registered for the user,\nand the credentials required to use them.\n", + "responses": { + "200": { + "description": "A list of external engines.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ExternalEngine" + } + } + } + } + } + } + }, + "post": { + "operationId": "apiExternalEngineCreate", + "summary": "Create external engine", + "tags": [ + "External engine" + ], + "security": [ + { + "OAuth2": [ + "engine:write" + ] + } + ], + "description": "Registers a new external engine for the user. It can then be selected\nand used on the analysis board.\n\nAfter registering, the provider should start waiting for analyis requests.\n", + "requestBody": { + "description": "A new external engine registration.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExternalEngineRegistration" + } + } + } + }, + "responses": { + "200": { + "description": "The registered engine.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExternalEngine" + } + } + } + } + } + } + }, + "/api/external-engine/{id}": { + "parameters": [ + { + "in": "path", + "name": "id", + "required": true, + "description": "The external engine id.", + "schema": { + "type": "string" + }, + "example": "eei_aTKImBJOnv6j" + } + ], + "get": { + "operationId": "apiExternalEngineGet", + "summary": "Get external engine", + "tags": [ + "External engine" + ], + "security": [ + { + "OAuth2": [ + "engine:read" + ] + } + ], + "description": "Get properties and credentials of an external engine.\n", + "responses": { + "200": { + "description": "A registered engine.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExternalEngine" + } + } + } + } + } + }, + "put": { + "operationId": "apiExternalEnginePut", + "summary": "Update external engine", + "tags": [ + "External engine" + ], + "security": [ + { + "OAuth2": [ + "engine:write" + ] + } + ], + "description": "Updates the properties of an external engine.\n", + "requestBody": { + "description": "A modified engine registration.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExternalEngineRegistration" + } + } + } + }, + "responses": { + "200": { + "description": "A registered engine.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExternalEngine" + } + } + } + } + } + }, + "delete": { + "operationId": "apiExternalEngineDelete", + "summary": "Delete external engine", + "tags": [ + "External engine" + ], + "security": [ + { + "OAuth2": [ + "engine:write" + ] + } + ], + "description": "Unregisters an external engine.\n", + "responses": { + "200": { + "description": "Engine successfully deleted", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + } + } + } + }, + "/api/external-engine/{id}/analyse": { + "servers": [ + { + "url": "https://engine.lichess.ovh" + } + ], + "parameters": [ + { + "in": "path", + "name": "id", + "required": true, + "description": "The external engine id.", + "schema": { + "type": "string" + }, + "example": "eei_aTKImBJOnv6j" + } + ], + "post": { + "operationId": "apiExternalEngineAnalyse", + "summary": "Analyse with external engine", + "tags": [ + "External engine" + ], + "security": [], + "description": "**Endpoint: `https://engine.lichess.ovh/api/external-engine/{id}/analyse`**\n\nRequest analysis from an external engine.\n\nResponse content is streamed as [newline delimited JSON](#section/Introduction/Streaming-with-ND-JSON).\nThe properties are based on the [UCI specification](https://backscattering.de/chess/uci/#engine).\nAnalysis stops when the client goes away, the requested limit\nis reached, or the provider goes away.\n", + "requestBody": { + "description": "Engine credentials and analysis request.", + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "clientSecret": { + "type": "string", + "example": "ees_mdF2hK0hlKGSPeC6" + }, + "work": { + "$ref": "#/components/schemas/ExternalEngineWork" + } + }, + "required": [ + "clientSecret", + "work" + ] + } + } + } + }, + "responses": { + "200": { + "description": "Stream of analysis output", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/x-ndjson": { + "schema": { + "type": "object", + "properties": { + "time": { + "type": "integer", + "description": "Number of milliseconds the search has been going on", + "example": 6880, + "minimum": 0 + }, + "depth": { + "type": "integer", + "description": "Current search depth", + "example": 25, + "minimum": 0 + }, + "nodes": { + "type": "integer", + "description": "Number of nodes visited so far", + "example": 7230340, + "minimum": 0 + }, + "pvs": { + "type": "array", + "description": "Information about up to 5 pvs, with the primary pv at index 0.", + "items": { + "type": "object", + "properties": { + "depth": { + "type": "integer", + "description": "Current search depth of the pv", + "example": 25, + "minimum": 0 + }, + "cp": { + "type": "integer", + "description": "Evaluation in centi-pawns, from White's point of view", + "example": 40 + }, + "mate": { + "type": "integer", + "description": "Evaluation in signed moves to mate, from White's point of view" + }, + "moves": { + "type": "array", + "description": "Variation in UCI notation", + "items": { + "type": "string" + }, + "example": [ + "e2e4", + "c7c6", + "g1f3", + "d7d5", + "d2d3", + "d5e4" + ] + } + }, + "required": [ + "depth", + "moves" + ] + } + } + }, + "required": [ + "time", + "depth", + "nodes", + "pvs" + ] + } + } + } + } + } + } + }, + "/api/external-engine/work": { + "servers": [ + { + "url": "https://engine.lichess.ovh" + } + ], + "post": { + "operationId": "apiExternalEngineAcquire", + "summary": "Acquire analysis request", + "tags": [ + "External engine" + ], + "security": [], + "description": "**Endpoint: `https://engine.lichess.ovh/api/external-engine/work`**\n\nWait for an analysis requests to any of the external engines that\nhave been registered with the given `secret`.\n\nUses long polling.\n\nAfter acquiring a request, the provider should immediately\n[start streaming the results](#tag/External-engine/operation/apiExternalEngineSubmit).\n", + "requestBody": { + "description": "Provider credentials.", + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "providerSecret": { + "type": "string", + "example": "Dee3uwieZei9ahpaici9bee2yahsai0K" + } + }, + "required": [ + "secret" + ] + } + } + } + }, + "responses": { + "200": { + "description": "Analysis has been requested", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "example": "aingoohiJee2sius" + }, + "work": { + "$ref": "#/components/schemas/ExternalEngineWork" + }, + "engine": { + "$ref": "#/components/schemas/ExternalEngine" + } + }, + "required": [ + "id", + "engine", + "work" + ] + } + } + } + }, + "204": { + "description": "No pending analysis", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + } + } + } + } + }, + "/api/external-engine/work/{id}": { + "servers": [ + { + "url": "https://engine.lichess.ovh" + } + ], + "parameters": [ + { + "in": "path", + "name": "id", + "required": true, + "schema": { + "type": "string", + "example": "aingoohiJee2sius" + } + } + ], + "post": { + "operationId": "apiExternalEngineSubmit", + "summary": "Answer analysis request", + "tags": [ + "External engine" + ], + "security": [], + "description": "**Endpoint: `https://engine.lichess.ovh/api/external-engine/work/{id}`**\n\nSubmit a stream of analysis as [UCI output](https://backscattering.de/chess/uci/#engine-info).\n\n* The engine should always be in `UCI_Chess960` mode.\n* `UCI_AnalyseMode` enabled if available.\n* It produces `info` with at least:\n - `depth`\n - `multipv` (between 1 and 5)\n - `score`\n - `nodes`\n - `time`\n - `pv`\n\nThe server may close the connection at any time, indicating that\nthe requester has gone away and analysis should be stopped.\n", + "requestBody": { + "description": "Analysis results", + "required": true, + "content": { + "text/plain": { + "schema": { + "type": "string" + }, + "example": "info multipv 1 depth 20 seldepth 30 time 1373 nodes 1494341 score cp 47 hashfull 594 nps 1088376 tbhits 0 pv d2d4 d7d5 c2c4 e7e6 b1c3 f8b4 c4d5 e6d5 g1f3 g8f6 c1g5 h7h6 g5f6 d8f6 d1b3 c7c5 e2e3 b8c6 d4c5 e8g8 f1d3" + } + } + }, + "responses": { + "200": { + "description": "Thanks", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + } + } + } + } + }, + "/oauth": { + "get": { + "operationId": "oauth", + "summary": "Request authorization code", + "tags": [ + "OAuth" + ], + "security": [], + "description": "OAuth2 authorization endpoint.\n\nStart the OAuth2 Authorization Code Flow with PKCE by securely\ngenerating two random strings unique to each authorization\nrequest:\n* `code_verifier`\n* `state`\n\nStore these in session storage. Make sure not to reveal `code_verifier`\nto eavesdroppers. Do not show it in URLs, do not abuse `state` to store\nit, do not send it over insecure connections. However it is fine if\nthe user themselves can extract `code_verifier`, which will always be\npossible for fully client-side apps.\n\nThen send the user to this endpoint. They will be prompted to grant\nauthorization and then be redirected back to the given `redirect_uri`.\n\nIf the authorization failed, the following query string parameters will\nbe appended to the redirection:\n* `error`, in particular with value `access_denied` if the user\n cancelled authorization\n* `error_description` to aid debugging\n* `state`, exactly as passed in the `state` parameter\n\nIf the authorization succeeded, the following query string parameters\nwill be appended to the redirection:\n* `code`, containing a fresh short-lived authorization code\n* `state`, exactly as passed in the `state` parameter\n\nNext, to defend against cross site request forgery, check that the\nreturned `state` matches the `state` you originally generated.\n\nFinally, continue by using the authorization code to\n[obtain an access token](#operation/apiToken).\n", + "parameters": [ + { + "in": "query", + "name": "response_type", + "description": "Must be `code`.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "in": "query", + "name": "client_id", + "description": "Arbitrary identifier that uniquely identifies your application.", + "example": "example.com", + "required": true, + "schema": { + "type": "string" + } + }, + { + "in": "query", + "name": "redirect_uri", + "description": "The absolute URL that the user should be redirected to with the authorization result.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "in": "query", + "name": "code_challenge_method", + "description": "Must be `S256`.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "in": "query", + "name": "code_challenge", + "description": "Compute `BASE64URL(SHA256(code_verifier))`.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "in": "query", + "name": "scope", + "description": "Space separated list of requested OAuth scopes, if any.", + "schema": { + "type": "string" + } + }, + { + "in": "query", + "name": "username", + "description": "Hint that you want the user to log in with a specific Lichess username.", + "schema": { + "type": "string" + } + }, + { + "in": "query", + "name": "state", + "description": "Arbitrary state that will be returned verbatim with the authorization result.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Authorization prompt will be displayed to the user." + } + } + } + }, + "/api/token": { + "post": { + "operationId": "apiToken", + "summary": "Obtain access token", + "tags": [ + "OAuth" + ], + "security": [], + "description": "OAuth2 token endpoint. Exchanges an authorization code for an access token.\n", + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "grant_type": { + "type": "string", + "example": "authorization_code", + "description": "Must be `authorization_code`." + }, + "code": { + "type": "string", + "example": "liu_iS1uOZg99Htmo58ex2jKgYziUfzsnAl0", + "description": "The authorization code that was sent in the `code` parameter to your `redirect_uri`." + }, + "code_verifier": { + "type": "string", + "example": "Ry1rbGdOMTQtUjhOc0lmTnFKak1LTHV0NjlRMll2aXYtTThkQnlJRkRpaGwyQjh0ZDNFdzFPSG9KUlY4M1NrRzJ5ZHhUdjVZR08zLTZOT3dCN2xLfjZOXzU2WHk4SENP", + "description": "A `code_challenge` was used to request the authorization code. This must be the `code_verifier` it was derived from." + }, + "redirect_uri": { + "type": "string", + "example": "http://example.com/", + "description": "Must match the `redirect_uri` used to request the authorization code." + }, + "client_id": { + "type": "string", + "example": "example.com", + "description": "Must match the `client_id` used to request the authorization code." + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Access token successfully obtained.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "example": { + "token_type": "Bearer", + "access_token": "lio_pLwAbN7lFPklzY2m8lTOI1DGApS84u57", + "expires_in": 31536000 + } + } + } + }, + "400": { + "description": "Failed to obtain access token.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OAuthError" + } + } + } + } + } + }, + "delete": { + "operationId": "apiTokenDelete", + "summary": "Revoke access token", + "description": "Revokes the access token sent as Bearer for this request.", + "tags": [ + "OAuth" + ], + "security": [ + { + "OAuth2": [] + } + ], + "responses": { + "204": { + "description": "Access token revoked.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + } + } + } + } + }, + "/api/token/test": { + "post": { + "operationId": "tokenTest", + "summary": "Test multiple OAuth tokens", + "description": "For up to 1000 OAuth tokens,\nreturns their associated user ID and scopes,\nor `null` if the token is invalid.\n\nThe method is `POST` so a longer list of tokens can be sent in the request body.\n", + "tags": [ + "OAuth" + ], + "security": [], + "requestBody": { + "description": "OAuth tokens separated by commas. Up to 1000.", + "required": true, + "content": { + "text/plain": { + "schema": { + "type": "string" + }, + "example": "lip_AvsS88TozFeSMEaoLN5c,lip_badToken" + } + } + }, + "responses": { + "200": { + "description": "The representation of the OAuth tokens.", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": { + "x-additionalPropertiesName": "token", + "oneOf": [ + { + "type": "object", + "properties": { + "userId": { + "type": "string" + }, + "scopes": { + "type": "string", + "description": "Comma-separated list of scopes. Empty string if the token has no scopes." + }, + "expires": { + "type": [ + "integer", + "null" + ], + "description": "Unix-timestampe in milliseconds or null if the token never expires." + } + } + }, + { + "type": "null" + } + ] + } + }, + "example": [ + { + "lip_AvsS88TozFeSnZa1LN5c": { + "scopes": "challenge:read,challenge:write", + "userId": "thibault", + "expires": 1358509698620 + }, + "lip_badToken": null + } + ] + } + } + } + } + } + } + }, + "/masters": { + "servers": [ + { + "url": "https://explorer.lichess.ovh" + } + ], + "get": { + "operationId": "openingExplorerMaster", + "summary": "Masters database", + "description": "**Endpoint: **\n\nExample: `curl https://explorer.lichess.ovh/masters?play=d2d4,d7d5,c2c4,c7c6,c4d5`\n", + "tags": [ + "Opening Explorer" + ], + "security": [], + "parameters": [ + { + "in": "query", + "name": "fen", + "description": "FEN of the root position", + "schema": { + "type": "string" + }, + "example": "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1" + }, + { + "in": "query", + "name": "play", + "description": "Comma separated sequence of legal moves in UCI notation.\nPlay additional moves starting from `fen`.\nRequired to find an opening name, if `fen` is not an exact match\nfor a named position.\n", + "schema": { + "type": "string", + "default": "" + }, + "example": "e2e4,e7e5,c2c4,c7c6,c4e5" + }, + { + "in": "query", + "name": "since", + "description": "Include only games from this year or later", + "schema": { + "type": "number", + "default": 1952 + } + }, + { + "in": "query", + "name": "until", + "description": "Include only games from this year or earlier", + "schema": { + "type": "number" + } + }, + { + "in": "query", + "name": "moves", + "description": "Number of most common moves to display", + "schema": { + "type": "number", + "default": 12 + } + }, + { + "in": "query", + "name": "topGames", + "description": "Number of top games to display", + "schema": { + "type": "number", + "default": 15, + "maximum": 15 + } + } + ], + "responses": { + "200": { + "description": "Opening statistics and game references for the position.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OpeningExplorerJson" + } + } + } + } + } + } + }, + "/lichess": { + "servers": [ + { + "url": "https://explorer.lichess.ovh" + } + ], + "get": { + "operationId": "openingExplorerLichess", + "summary": "Lichess games", + "description": "**Endpoint: **\n\nGames sampled from all Lichess players.\n\nExample: `curl https://explorer.lichess.ovh/lichess?variant=standard&speeds=blitz,rapid,classical&ratings=2200,2500&fen=rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR%20w%20KQkq%20-%200%201`\n", + "tags": [ + "Opening Explorer" + ], + "security": [], + "parameters": [ + { + "in": "query", + "name": "variant", + "description": "Variant", + "schema": { + "$ref": "#/components/schemas/VariantKey", + "default": "standard" + } + }, + { + "in": "query", + "name": "fen", + "description": "FEN of the root position", + "schema": { + "type": "string" + }, + "example": "rnbqkbnr/ppp1pppp/8/3pP3/8/8/PPPP1PPP/RNBQKBNR b KQkq - 0 2" + }, + { + "in": "query", + "name": "play", + "description": "Comma separated sequence of legal moves in UCI notation.\nPlay additional moves starting from `fen`.\nRequired to find an opening name, if `fen` is not an exact match\nfor a named position.\n", + "schema": { + "type": "string", + "default": "" + }, + "example": "e2e4,e7e5,c2c4,c7c6,c4e5" + }, + { + "in": "query", + "name": "speeds", + "description": "Comma separated list of game speeds to look for", + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Speed" + } + } + }, + { + "in": "query", + "name": "ratings", + "description": "Comma separated list of rating groups, ranging from their value to the next higher group", + "schema": { + "type": "array", + "items": { + "type": "number", + "enum": [ + 0, + 1000, + 1200, + 1400, + 1600, + 1800, + 2000, + 2200, + 2500 + ] + } + } + }, + { + "in": "query", + "name": "since", + "description": "Include only games from this month or later", + "schema": { + "type": "string", + "default": "1952-01" + } + }, + { + "in": "query", + "name": "until", + "description": "Include only games from this month or earlier", + "schema": { + "type": "string", + "default": "3000-12" + } + }, + { + "in": "query", + "name": "moves", + "description": "Number of most common moves to display", + "schema": { + "type": "number", + "default": 12 + } + }, + { + "in": "query", + "name": "topGames", + "description": "Number of top games to display", + "schema": { + "type": "number", + "default": 4, + "maximum": 4 + } + }, + { + "in": "query", + "name": "recentGames", + "description": "Number of recent games to display", + "schema": { + "type": "number", + "default": 4, + "maximum": 4 + } + } + ], + "responses": { + "200": { + "description": "Opening statistics and game references for the position.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OpeningExplorerJson" + } + } + } + } + } + } + }, + "/lichess/history": { + "servers": [ + { + "url": "https://explorer.lichess.ovh" + } + ], + "get": { + "operationId": "openingExplorerLichessHistory", + "summary": "Lichess games history", + "description": "**Endpoint: **\n\nOpening statistics of games sampled from all Lichess players, grouped\nby month. Starts with the first month that has any data,\nor at `since` if given.\n", + "tags": [ + "Opening Explorer" + ], + "security": [], + "parameters": [ + { + "in": "query", + "name": "variant", + "description": "Variant", + "schema": { + "$ref": "#/components/schemas/VariantKey", + "default": "standard" + } + }, + { + "in": "query", + "name": "fen", + "description": "FEN of the root position", + "schema": { + "type": "string" + }, + "example": "rnbqkbnr/ppp1pppp/8/3pP3/8/8/PPPP1PPP/RNBQKBNR b KQkq - 0 2" + }, + { + "in": "query", + "name": "play", + "description": "Comma separated sequence of legal moves in UCI notation.\nPlay additional moves starting from `fen`.\nRequired to find an opening name, if `fen` is not an exact match\nfor a named position.\n", + "schema": { + "type": "string", + "default": "" + }, + "example": "e2e4,e7e5,c2c4,c7c6,c4e5" + }, + { + "in": "query", + "name": "speeds", + "description": "Comma separated list of game speeds to look for", + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Speed" + } + } + }, + { + "in": "query", + "name": "ratings", + "description": "Comma separated list of rating groups, ranging from their value to the next higher group", + "schema": { + "type": "array", + "items": { + "type": "number", + "enum": [ + 0, + 1000, + 1200, + 1400, + 1600, + 1800, + 2000, + 2200, + 2500 + ] + } + } + }, + { + "in": "query", + "name": "since", + "description": "Include only games from this month or later", + "schema": { + "type": "string", + "example": "2017-04" + } + }, + { + "in": "query", + "name": "until", + "description": "Include only games from this month or earlier", + "schema": { + "type": "string", + "default": "3000-12" + } + } + ], + "responses": { + "200": { + "description": "Opening statistics over time.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "example": { + "history": [ + { + "month": "2017-04", + "black": 413538, + "draws": 38549, + "white": 429805 + }, + { + "month": "2017-05", + "black": 418542, + "draws": 39171, + "white": 434066 + } + ], + "opening": { + "eco": "B00", + "name": "King's Pawn" + } + } + } + } + } + } + } + } + }, + "/player": { + "servers": [ + { + "url": "https://explorer.lichess.ovh" + } + ], + "get": { + "operationId": "openingExplorerPlayer", + "summary": "Player games", + "description": "**Endpoint: **\n\nGames of a Lichess player.\n\nResponds with a stream of [newline delimited JSON](#section/Introduction/Streaming-with-ND-JSON). Will start indexing\non demand, immediately respond with the current results, and stream\nmore updates until indexing is complete. The stream is throttled\nand deduplicated. Empty lines may be sent to avoid timeouts.\n\nWill index new games at most once per minute, and revisit previously\nongoing games at most once every day.\n\nExample: `curl https://explorer.lichess.ovh/player?player=revoof&color=white&play=d2d4,d7d5&recentGames=1`\n", + "tags": [ + "Opening Explorer" + ], + "security": [], + "parameters": [ + { + "in": "query", + "name": "player", + "description": "Username or ID of the player", + "schema": { + "type": "string" + }, + "example": "revoof" + }, + { + "in": "query", + "name": "variant", + "description": "Variant", + "schema": { + "$ref": "#/components/schemas/VariantKey", + "default": "standard" + } + }, + { + "in": "query", + "name": "fen", + "description": "FEN of the root position", + "schema": { + "type": "string" + }, + "example": "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1" + }, + { + "in": "query", + "name": "play", + "description": "Comma separated sequence of legal moves in UCI notation.\nPlay additional moves starting from `fen`.\nRequired to find an opening name, if `fen` is not an exact match\nfor a named position.\n", + "schema": { + "type": "string", + "default": "" + }, + "example": "d2d4,d7d5" + }, + { + "in": "query", + "name": "speeds", + "description": "Comma separated list of game speeds to look for", + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Speed" + } + } + }, + { + "in": "query", + "name": "modes", + "description": "Comma separated list of modes", + "schema": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "casual", + "rated" + ] + } + } + }, + { + "in": "query", + "name": "since", + "description": "Include only games from this month or later", + "schema": { + "type": "string", + "default": "1952-01" + } + }, + { + "in": "query", + "name": "until", + "description": "Include only games from this month or earlier", + "schema": { + "type": "string", + "default": "3000-12" + } + }, + { + "in": "query", + "name": "moves", + "description": "Number of most common moves to display", + "schema": { + "type": "number" + } + }, + { + "in": "query", + "name": "recentGames", + "description": "Number of recent games to display", + "schema": { + "type": "number", + "default": 8, + "maximum": 8 + } + } + ], + "responses": { + "200": { + "description": "Opening statistics and game references for the position.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/nd-json": { + "schema": { + "$ref": "#/components/schemas/OpeningExplorerPlayerJson" + } + } + } + } + } + } + }, + "/master/pgn/{gameId}": { + "servers": [ + { + "url": "https://explorer.lichess.ovh" + } + ], + "get": { + "operationId": "openingExplorerMasterGame", + "summary": "OTB master game", + "description": "**Endpoint: `https://explorer.lichess.ovh/masters/pgn/{gameId}`**\n\nExample: `curl https://explorer.lichess.ovh/masters/pgn/aAbqI4ey`\n", + "tags": [ + "Opening Explorer" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "gameId", + "schema": { + "type": "string" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The PGN representation of the game.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/x-chess-pgn": { + "schema": { + "$ref": "#/components/schemas/MasterGamePgn" + } + } + } + } + } + } + }, + "/standard": { + "servers": [ + { + "url": "https://tablebase.lichess.ovh" + } + ], + "get": { + "operationId": "tablebaseStandard", + "summary": "Tablebase lookup", + "description": "**Endpoint: **\n\nExample: `curl http://tablebase.lichess.ovh/standard?fen=4k3/6KP/8/8/8/8/7p/8_w_-_-_0_1`\n", + "tags": [ + "Tablebase" + ], + "security": [], + "parameters": [ + { + "in": "query", + "name": "fen", + "description": "FEN of the position. Underscores allowed.", + "schema": { + "type": "string" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The tablebase information for the position in standard chess.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TablebaseJson" + } + } + } + } + } + } + }, + "/atomic": { + "servers": [ + { + "url": "https://tablebase.lichess.ovh" + } + ], + "get": { + "operationId": "tablebaseAtomic", + "summary": "Tablebase lookup for Atomic chess", + "description": "**Endpoint: **\n", + "tags": [ + "Tablebase" + ], + "security": [], + "responses": { + "200": { + "description": "The tablebase information for the position in atomic chess.", + "content": { + "text/plain": { + "schema": { + "type": "string" + } + } + }, + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + } + } + } + } + }, + "/antichess": { + "servers": [ + { + "url": "https://tablebase.lichess.ovh" + } + ], + "get": { + "operationId": "antichessAtomic", + "summary": "Tablebase lookup for Antichess", + "description": "**Endpoint: **\n", + "tags": [ + "Tablebase" + ], + "security": [], + "responses": { + "200": { + "description": "The tablebase information for the position in atomic chess.", + "content": { + "text/plain": { + "schema": { + "type": "string" + } + } + }, + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + } + } + } + } + } + }, + "components": { + "schemas": { + "VariantKey": { + "type": "string", + "enum": [ + "standard", + "chess960", + "crazyhouse", + "antichess", + "atomic", + "horde", + "kingOfTheHill", + "racingKings", + "threeCheck", + "fromPosition" + ], + "example": "standard", + "default": "standard" + }, + "Variant": { + "type": "object", + "properties": { + "key": { + "$ref": "#/components/schemas/VariantKey" + }, + "name": { + "type": "string" + }, + "short": { + "type": "string" + } + } + }, + "UciVariant": { + "type": "string", + "enum": [ + "chess", + "crazyhouse", + "antichess", + "atomic", + "horde", + "kingofthehill", + "racingkings", + "3check" + ], + "example": "chess", + "default": "chess" + }, + "Speed": { + "type": "string", + "enum": [ + "ultraBullet", + "bullet", + "blitz", + "rapid", + "classical", + "correspondence" + ] + }, + "PerfType": { + "type": "string", + "enum": [ + "ultraBullet", + "bullet", + "blitz", + "rapid", + "classical", + "correspondence", + "chess960", + "crazyhouse", + "antichess", + "atomic", + "horde", + "kingOfTheHill", + "racingKings", + "threeCheck" + ] + }, + "Clock": { + "type": "object", + "properties": { + "limit": { + "type": "integer" + }, + "increment": { + "type": "integer" + } + } + }, + "GameStatus": { + "type": "string", + "description": "Game status code. https://github.com/ornicar/scalachess/blob/0a7d6f2c63b1ca06cd3c958ed3264e738af5c5f6/src/main/scala/Status.scala#L16-L28", + "enum": [ + "created", + "started", + "aborted", + "mate", + "resign", + "stalemate", + "timeout", + "draw", + "outoftime", + "cheat", + "noStart", + "unknownFinish", + "variantEnd" + ] + }, + "FromPositionFEN": { + "type": "string", + "description": "Custom initial position (in FEN). Variant must be standard, fromPosition, or chess960 (if a valid 960 starting position), and the game cannot be rated.", + "default": "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1" + }, + "ChallengeUser": { + "allOf": [ + { + "$ref": "#/components/schemas/LightUser" + } + ], + "properties": { + "rating": { + "type": "number" + }, + "provisional": { + "type": "boolean" + }, + "online": { + "type": "boolean" + } + } + }, + "ChallengeJson": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "url": { + "type": "string" + }, + "status": { + "type": "string", + "enum": [ + "created", + "offline", + "canceled", + "declined", + "accepted" + ] + }, + "challenger": { + "$ref": "#/components/schemas/ChallengeUser" + }, + "destUser": { + "oneOf": [ + { + "$ref": "#/components/schemas/ChallengeUser" + }, + { + "type": "null" + } + ] + }, + "variant": { + "$ref": "#/components/schemas/Variant" + }, + "rated": { + "type": "boolean" + }, + "speed": { + "$ref": "#/components/schemas/Speed" + }, + "timeControl": { + "oneOf": [ + { + "type": "object", + "properties": { + "type": { + "type": "string", + "example": "clock" + }, + "limit": { + "type": "number" + }, + "increment": { + "type": "number" + }, + "show": { + "example": "5+2", + "type": "string" + } + }, + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "example": "correspondence" + }, + "daysPerTurn": { + "type": "number" + } + }, + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "example": "unlimited" + } + }, + "additionalProperties": false + } + ] + }, + "color": { + "type": "string", + "enum": [ + "white", + "black", + "random" + ] + }, + "perf": { + "type": "object", + "properties": { + "icon": { + "type": "string" + }, + "name": { + "type": "string" + } + } + }, + "direction": { + "type": "string", + "enum": [ + "in", + "out" + ] + }, + "initialFen": { + "type": "string" + }, + "declineReason": { + "type": "string", + "description": "Human readable, possibly translated reason why the challenge was declined." + }, + "declineReasonKey": { + "type": "string", + "description": "Untranslated, computer-matchable reason why the challenge was declined." + } + }, + "required": [ + "id", + "url", + "status", + "challenger", + "destUser", + "variant", + "rated", + "speed", + "timeControl", + "color", + "perf" + ], + "example": { + "id": "VU0nyvsW", + "url": "https://lichess.org/VU0nyvsW", + "color": "random", + "direction": "out", + "timeControl": { + "increment": 2, + "limit": 300, + "show": "5+2", + "type": "clock" + }, + "variant": { + "key": "standard", + "name": "Standard", + "short": "Std" + }, + "challenger": { + "id": "thibot", + "name": "thibot", + "online": true, + "provisional": false, + "rating": 1940, + "title": "BOT" + }, + "destUser": { + "id": "leelachess", + "name": "LeelaChess", + "online": true, + "provisional": true, + "rating": 2670, + "title": "BOT" + }, + "perf": { + "icon": ";", + "name": "Correspondence" + }, + "rated": true, + "speed": "blitz", + "status": "created" + } + }, + "ChallengeCanceledJson": { + "type": "object", + "properties": { + "id": { + "type": "string" + } + }, + "example": { + "id": "VU0nyvsW" + } + }, + "ChallengeOpenJson": { + "example": { + "id": "VU0nyvsW", + "url": "https://lichess.org/VU0nyvsW", + "urlWhite": "https://lichess.org/VU0nyvsW?color=white", + "urlBlack": "https://lichess.org/VU0nyvsW?color=black", + "color": "random", + "direction": "out", + "timeControl": { + "increment": 2, + "limit": 300, + "show": "5+2", + "type": "clock" + }, + "variant": { + "key": "standard", + "name": "Standard", + "short": "Std" + }, + "challenger": { + "id": "thibot", + "name": "thibot", + "online": true, + "provisional": false, + "rating": 1940, + "title": "BOT" + }, + "destUser": { + "id": "leelachess", + "name": "LeelaChess", + "online": true, + "provisional": true, + "rating": 2670, + "title": "BOT" + }, + "perf": { + "icon": ";", + "name": "Correspondence" + }, + "rated": true, + "speed": "blitz", + "status": "created" + } + }, + "BulkPairing": { + "example": { + "id": "RVAcwgg7", + "games": [ + { + "id": "NKop9IyD", + "black": "lizen1", + "white": "thibault" + }, + { + "id": "KT8374ut", + "black": "lizen3", + "white": "lizen2" + }, + { + "id": "wInQr8Sk", + "black": "lizen5", + "white": "lizen4" + } + ], + "variant": "standard", + "clock": { + "increment": 0, + "limit": 300 + }, + "pairAt": 1612289869919, + "pairedAt": null, + "rated": false, + "startClocksAt": 1612200422971, + "scheduledAt": 1612203514628 + } + }, + "GameUser": { + "type": "object", + "properties": { + "user": { + "$ref": "#/components/schemas/LightUser" + }, + "rating": { + "type": "number" + }, + "ratingDiff": { + "type": "number" + }, + "name": { + "type": "string" + }, + "provisional": { + "type": "boolean" + }, + "aiLevel": { + "type": "number" + }, + "analysis": { + "type": "object", + "properties": { + "inaccuracy": { + "type": "number" + }, + "mistake": { + "type": "number" + }, + "blunder": { + "type": "number" + }, + "acpl": { + "type": "number" + } + }, + "required": [ + "inaccuracy", + "mistake", + "blunder", + "acpl" + ] + }, + "team": { + "type": "string" + } + } + }, + "GameJson": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "rated": { + "type": "boolean" + }, + "variant": { + "$ref": "#/components/schemas/VariantKey" + }, + "speed": { + "$ref": "#/components/schemas/Speed" + }, + "perf": { + "type": "string" + }, + "createdAt": { + "type": "number", + "format": "int64" + }, + "lastMoveAt": { + "type": "number", + "format": "int64" + }, + "status": { + "$ref": "#/components/schemas/GameStatus" + }, + "players": { + "type": "object", + "properties": { + "white": { + "$ref": "#/components/schemas/GameUser" + }, + "black": { + "$ref": "#/components/schemas/GameUser" + } + } + }, + "initialFen": { + "type": "string" + }, + "winner": { + "type": "string", + "enum": [ + "white", + "black" + ] + }, + "opening": { + "type": "object", + "properties": { + "eco": { + "type": "string" + }, + "name": { + "type": "string" + }, + "ply": { + "type": "number" + } + } + }, + "moves": { + "type": "string" + }, + "pgn": { + "type": "string" + }, + "daysPerTurn": { + "type": "number" + }, + "analysis": { + "type": "array", + "items": { + "type": "object", + "properties": { + "eval": { + "type": "number", + "description": "Evaluation in centipawns" + }, + "best": { + "type": "string", + "example": "c2c3", + "description": "Best move in UCI notation (only if played move was inaccurate)" + }, + "variation": { + "type": "string", + "example": "c3 Nc6 d4 Qb6 Be2 Nge7 Na3 cxd4 cxd4 Nf5", + "description": "Best variation in SAN notation (only if played move was inaccurate)" + }, + "judgment": { + "type": "object", + "description": "Judgment annotation (only if played move was inaccurate)", + "properties": { + "name": { + "type": "string", + "enum": [ + "Inaccuracy", + "Mistake", + "Blunder" + ] + }, + "comment": { + "type": "string", + "example": "Blunder. Nxg6 was best." + } + } + } + }, + "required": [ + "eval" + ] + } + }, + "tournament": { + "type": "string" + }, + "swiss": { + "type": "string" + }, + "clock": { + "type": "object", + "properties": { + "initial": { + "type": "number" + }, + "increment": { + "type": "number" + }, + "totalTime": { + "type": "number" + } + } + } + }, + "required": [ + "id", + "rated", + "variant", + "speed", + "perf", + "createdAt", + "lastMoveAt", + "status", + "players" + ], + "example": { + "id": "q7ZvsdUF", + "rated": true, + "variant": "standard", + "speed": "blitz", + "perf": "blitz", + "createdAt": 1514505150384, + "lastMoveAt": 1514505592843, + "status": "draw", + "players": { + "white": { + "user": { + "name": "Lance5500", + "title": "LM", + "patron": true, + "id": "lance5500" + }, + "rating": 2389, + "ratingDiff": 4 + }, + "black": { + "user": { + "name": "TryingHard87", + "id": "tryinghard87" + }, + "rating": 2498, + "ratingDiff": -4 + } + }, + "opening": { + "eco": "D31", + "name": "Semi-Slav Defense: Marshall Gambit", + "ply": 7 + }, + "moves": "d4 d5 c4 c6 Nc3 e6 e4 Nd7 exd5 cxd5 cxd5 exd5 Nxd5 Nb6 Bb5+ Bd7 Qe2+ Ne7 Nxb6 Qxb6 Bxd7+ Kxd7 Nf3 Qa6 Ne5+ Ke8 Qf3 f6 Nd3 Qc6 Qe2 Kf7 O-O Kg8 Bd2 Re8 Rac1 Nf5 Be3 Qe6 Rfe1 g6 b3 Bd6 Qd2 Kf7 Bf4 Qd7 Bxd6 Nxd6 Nc5 Rxe1+ Rxe1 Qc6 f3 Re8 Rxe8 Nxe8 Kf2 Nc7 Qb4 b6 Qc4+ Nd5 Nd3 Qe6 Nb4 Ne7 Qxe6+ Kxe6 Ke3 Kd6 g3 h6 Kd3 h5 Nc2 Kd5 a3 Nc6 Ne3+ Kd6 h4 Nd8 g4 Ne6 Ke4 Ng7 Nc4+ Ke6 d5+ Kd7 a4 g5 gxh5 Nxh5 hxg5 fxg5 Kf5 Nf4 Ne3 Nh3 Kg4 Ng1 Nc4 Kc7 Nd2 Kd6 Kxg5 Kxd5 f4 Nh3+ Kg4 Nf2+ Kf3 Nd3 Ke3 Nc5 Kf3 Ke6 Ke3 Kf5 Kd4 Ne6+ Kc4", + "clock": { + "initial": 300, + "increment": 3, + "totalTime": 420 + } + } + }, + "GamePgn": { + "example": "[Event \"Rated Blitz game\"]\n[Site \"https://lichess.org/fY44h4OY\"]\n[Date \"2018.03.29\"]\n[Round \"-\"]\n[White \"pveldman\"]\n[Black \"thibault\"]\n[Result \"1-0\"]\n[UTCDate \"2018.03.29\"]\n[UTCTime \"01:38:15\"]\n[WhiteElo \"1610\"]\n[BlackElo \"1601\"]\n[WhiteRatingDiff \"+10\"]\n[BlackRatingDiff \"-10\"]\n[Variant \"Standard\"]\n[TimeControl \"180+0\"]\n[ECO \"C62\"]\n[Opening \"Ruy Lopez: Steinitz Defense\"]\n[Termination \"Normal\"]\n[Event \"U1700 SuperBlitz Arena\"]\n\n1. e4 { [%clk 0:03:00] } e5 { [%clk 0:03:00] } 2. Nf3 { [%clk 0:02:59] } Nc6 { [%clk 0:02:58] } 3. Bb5 { [%clk 0:02:57] } d6 { [%clk 0:02:55] } 4. h3 { [%clk 0:02:54] } Nf6 { [%clk 0:02:52] } 5. Bxc6+ { [%clk 0:02:52] } bxc6 { [%clk 0:02:49] } 6. d3 { [%clk 0:02:51] } Be7 { [%clk 0:02:46] } 7. O-O { [%clk 0:02:47] } O-O { [%clk 0:02:45] } 8. b3 { [%clk 0:02:45] } d5 { [%clk 0:02:45] } 9. exd5 { [%clk 0:02:33] } cxd5 { [%clk 0:02:40] } 10. Nxe5 { [%clk 0:02:31] } Qd6 { [%clk 0:02:38] } 1-0\n" + }, + "MasterGamePgn": { + "example": "[Event \"Wch Blitz\"]\n[Site \"Astana\"]\n[Date \"2012.07.10\"]\n[Round \"23\"]\n[White \"Carlsen, Magnus\"]\n[Black \"Chadaev, Nikolay\"]\n[Result \"1-0\"]\n[WhiteElo \"2837\"]\n[BlackElo \"2580\"]\n\n1. e4 e5 2. f4 d5 3. exd5 exf4 4. Nf3 Nf6 5. c4 c6 6. d4 cxd5 7. c5 Nc6 8. Bb5 Be7 9. O-O O-O 10. Bxf4 Bg4 11. Nc3 Ne4 12. Qd3 Bf5 13. Qe3 Bf6 14. Bxc6 bxc6 15. Ne5 Bxe5 16. Bxe5 Bg6 17. Nxe4 Bxe4 18. Qg3 f6 19. Bd6 Re8 20. b4 Bg6 21. a4 a6 22. h4 Qd7 23. h5 Bxh5 24. Rxf6 Qg4 25. Qxg4 Bxg4 26. Rf4 Bh5 27. Raf1 h6 28. Be5 Ra7 29. b5 axb5 30. axb5 cxb5 31. c6 Raa8 32. c7 Kh7 33. Rb1 Be2 34. Rf7 Rg8 35. Re7 Bc4 36. Kh2 Rae8 37. Rd7 Ra8 38. Rb2 Raf8 39. g4 Ra8 40. Rf2 b4 41. Rff7 h5 42. Rxg7+ Rxg7 43. Rxg7+ 1-0\n" + }, + "StudyPgn": { + "example": "[Event \"All about the Sicilian Defense: Dragon Variation\"]\n[Site \"https://lichess.org/study/8c8bmUfy/qwnXMwVC\"]\n[Result \"*\"]\n[UTCDate \"2017.06.25\"]\n[UTCTime \"10:12:04\"]\n[Variant \"Standard\"]\n[ECO \"B76\"]\n[Opening \"Sicilian Defense: Dragon Variation, Yugoslav Attack, Panov Variation\"]\n[Annotator \"https://lichess.org/@/Francesco_Super\"]\n\n{ This chapter will go over the Dragon Variation, a very common variation used by Black and it is the most aggressive variation in the Sicilian defense. }\n1. e4 c5 2. Nf3 { Simple developing move to control the d4 square } { [%csl Gd4,Gc5][%cal Gf3d4,Gc5d4] } 2... d6 { [%cal Gd6e5] } (2... e6 3. d4 cxd4 4. Nxd4 Nf6 5. e5 (5. Nc3 { [%cal Ge4e5] }) 5... Qa5+) 3. d4 { Whites want the exchange of pawns } { [%cal Gc5d4] } 3... cxd4 { [%cal Gf3d4] } 4. Nxd4 { Whites are now ahead in development but blacks still have the two central pawns whereas whites only one. } { [%csl Ge7,Gd6,Ge4] } 4... Nf6 { Blacks are now developing their knight and threatening the e4 pawn } { [%csl Ge4][%cal Gf6e4] } 5. Nc3 { The e4 pawn is now protected by the c3 knight } { [%csl Ge4,Bc3][%cal Rf6e4,Bc3e4] } 5... g6 { This is the DRAGON VARIATION. g6 allows the dark-squared bishop to develop and move to g7, controlling the long dark-squared diagonal } { [%csl Gd4] } 6. Be3 { [%cal Gd1d2,Gf2f3,Ge1c1,Gg2g4,Gh2h4,Gg4g5] } (6. Be2 Bg7 7. O-O Nc6 8. Be3 { [%cal Ge3d4] } (8. f3 Nxe4 { [%cal Gg7d4,Gc6d4] } 9. Nxc6 Qb6+ { [%cal Gb6c6,Gb6g1] } 10. Kh1 Nxc3 { [%cal Gc3d1,Gc3e2] } 11. bxc3 bxc6 { [%cal Gc8a6] }) 8... O-O 9. Nb3 a6 { [%cal Gb7b5,Gb5b4,Ge2c4] }) 6... Bg7 (6... Ng4 { [%cal Gg4e3] } 7. Bb5+ { [%cal Gb5e8,Gb8d7,Gc8d7,Gd1g4] } 7... Nc6 8. Nxc6 bxc6 9. Bxc6+ { [%cal Gc6a8] }) 7. f3 { The key opening moves for White, who attempt to castle queenside , whereas f3 strengthens the pawn structure, connecting e4 to the h2 and g2, while White also plan pushing to g4 and possibly h4. } { [%csl Bf3,Be3][%cal Rg2g4,Rh2h4,Rg4g5] } 7... O-O (7... h5 { Is operating against g4. }) 8. Qd2 { [%csl Gh6,Gg7][%cal Ge1c1,Ga1d1,Re3h6,Rd2h6] } 8... Nc6 { [%csl Gc6,Gh6][%cal Gb8c6,Ge1c1,Ga7a6,Ge3h6] } 9. g4 (9. Bh6 { [%cal Ge3d4] } 9... Bxh6 10. Qxh6 Nxd4) 9... Be6 10. Nxe6 fxe6 { [%cal Gf8f1] } 11. O-O-O Ne5 12. Be2 { [%csl Gf3][%cal Re5f3,Bd1h1,Bg1d1] } 12... Qc7 { [%csl Gc4][%cal Ge5c4,Gc4e3,Gc4d2,Bf8c8,Yc7c3] } 13. h4 Nc4 *\n" + }, + "Title": { + "type": "string", + "enum": [ + "GM", + "WGM", + "IM", + "WIM", + "FM", + "WFM", + "NM", + "CM", + "WCM", + "WNM", + "LM", + "BOT" + ], + "example": "NM" + }, + "LightUser": { + "type": "object", + "properties": { + "id": { + "type": "string", + "example": "chess-network" + }, + "name": { + "type": "string", + "example": "Chess-Network" + }, + "title": { + "$ref": "#/components/schemas/Title" + }, + "patron": { + "type": "boolean", + "example": true + } + }, + "required": [ + "id", + "name" + ] + }, + "LightUserOnline": { + "allOf": [ + { + "$ref": "#/components/schemas/LightUser" + }, + { + "properties": { + "online": { + "type": "boolean" + } + } + } + ] + }, + "Perf": { + "type": "object", + "properties": { + "games": { + "type": "integer", + "example": 2945 + }, + "rating": { + "type": "integer", + "example": 1609 + }, + "rd": { + "type": "integer", + "example": 60 + }, + "prog": { + "type": "integer", + "example": -22 + }, + "prov": { + "type": "boolean" + } + } + }, + "StormPerf": { + "type": "object", + "properties": { + "runs": { + "type": "integer", + "example": 44 + }, + "score": { + "type": "integer", + "example": 61 + } + } + }, + "Perfs": { + "type": "object", + "properties": { + "chess960": { + "$ref": "#/components/schemas/Perf" + }, + "atomic": { + "$ref": "#/components/schemas/Perf" + }, + "racingKings": { + "$ref": "#/components/schemas/Perf" + }, + "ultraBullet": { + "$ref": "#/components/schemas/Perf" + }, + "blitz": { + "$ref": "#/components/schemas/Perf" + }, + "kingOfTheHill": { + "$ref": "#/components/schemas/Perf" + }, + "bullet": { + "$ref": "#/components/schemas/Perf" + }, + "correspondence": { + "$ref": "#/components/schemas/Perf" + }, + "horde": { + "$ref": "#/components/schemas/Perf" + }, + "puzzle": { + "$ref": "#/components/schemas/Perf" + }, + "classical": { + "$ref": "#/components/schemas/Perf" + }, + "rapid": { + "$ref": "#/components/schemas/Perf" + }, + "storm": { + "$ref": "#/components/schemas/StormPerf" + } + } + }, + "PlayTime": { + "type": "object", + "properties": { + "total": { + "type": "integer", + "example": 3296897 + }, + "tv": { + "type": "integer", + "example": 12134 + } + } + }, + "Profile": { + "type": "object", + "properties": { + "country": { + "type": "string", + "example": "EC" + }, + "location": { + "type": "string" + }, + "bio": { + "type": "string", + "example": "Free bugs!" + }, + "firstName": { + "type": "string", + "example": "Thibault" + }, + "lastName": { + "type": "string", + "example": "Duplessis" + }, + "fideRating": { + "type": "integer", + "example": 1500 + }, + "uscfRating": { + "type": "integer", + "example": 1500 + }, + "ecfRating": { + "type": "integer", + "example": 1500 + }, + "links": { + "type": "string", + "example": "github.com/ornicar\r\ntwitter.com/ornicar" + } + } + }, + "Count": { + "type": "object", + "properties": { + "all": { + "type": "integer", + "example": 9265 + }, + "rated": { + "type": "integer", + "example": 7157 + }, + "ai": { + "type": "integer", + "example": 531 + }, + "draw": { + "type": "integer", + "example": 340 + }, + "drawH": { + "type": "integer", + "example": 331 + }, + "loss": { + "type": "integer", + "example": 4480 + }, + "lossH": { + "type": "integer", + "example": 4207 + }, + "win": { + "type": "integer", + "example": 4440 + }, + "winH": { + "type": "integer", + "example": 4378 + }, + "bookmark": { + "type": "integer", + "example": 71 + }, + "playing": { + "type": "integer", + "example": 6 + }, + "import": { + "type": "integer", + "example": 66 + }, + "me": { + "type": "integer", + "example": 0 + } + } + }, + "User": { + "type": "object", + "properties": { + "id": { + "type": "string", + "example": "georges" + }, + "username": { + "type": "string", + "example": "Georges" + }, + "perfs": { + "$ref": "#/components/schemas/Perfs" + }, + "createdAt": { + "type": "integer", + "format": "int64", + "example": 1290415680000 + }, + "disabled": { + "type": "boolean", + "example": false + }, + "tosViolation": { + "type": "boolean", + "example": false + }, + "profile": { + "$ref": "#/components/schemas/Profile" + }, + "seenAt": { + "type": "integer", + "format": "int64", + "example": 1522636452014 + }, + "patron": { + "type": "boolean", + "example": true + }, + "verified": { + "type": "boolean", + "example": true + }, + "playTime": { + "$ref": "#/components/schemas/PlayTime" + }, + "title": { + "$ref": "#/components/schemas/Title" + } + } + }, + "UserExtended": { + "allOf": [ + { + "$ref": "#/components/schemas/User" + }, + { + "properties": { + "url": { + "type": "string", + "format": "uri", + "example": "https://lichess.org/@/georges" + }, + "playing": { + "type": "string", + "format": "uri", + "example": "https://lichess.org/yqfLYJ5E/black" + }, + "count": { + "$ref": "#/components/schemas/Count" + }, + "streaming": { + "type": "boolean", + "example": false + }, + "followable": { + "type": "boolean", + "example": true + }, + "following": { + "type": "boolean", + "example": false + }, + "blocking": { + "type": "boolean", + "example": false + }, + "followsYou": { + "type": "boolean", + "example": false + } + } + } + ] + }, + "Crosstable": { + "example": { + "users": { + "neio": 201.5, + "thibault": 144.5 + }, + "nbGames": 346, + "matchup": { + "users": { + "neio": 44, + "thibault": 43 + }, + "nbGames": 87 + } + } + }, + "GameChat": { + "example": [ + { + "text": "Takeback sent", + "user": "lichess" + }, + { + "text": "Takeback accepted", + "user": "lichess" + }, + { + "text": "Good game, well played", + "user": "thibault" + } + ] + }, + "PuzzleJson": { + "example": { + "game": { + "clock": "10+0", + "id": "VpVdGbna", + "perf": { + "key": "rapid", + "name": "Rapid" + }, + "pgn": "d4 Nf6 Nf3 g6 Nc3 d6 e4 c5 Be3 cxd4 Bxd4 Nc6 Be3 Qa5 Bd2 Bg7 Be2 O-O O-O Qb6 Rb1 Bg4 h3 Bxf3 Bxf3 Nd4 Be3 Nxf3+ Qxf3 Qc6 Bd4 a6 Bxf6 Bxf6 Nd5 Qxc2 Nxf6+ exf6 Qxf6 Qxe4 Qxd6 Rad8 Qb6 Rfe8 Rfe1 Qxe1+ Rxe1 Rxe1+ Kh2 Rd2 Kg3 Ree2 Qxb7 Rxb2 Qxa6 Rxa2 Qc8+ Kg7 Qc3+ Kg8 Qc5 Rxf2 Qc8+ Kg7 Qc3+ Kh6 Qe3+ Kg7 Qe5+ Kf8 Qh8+ Ke7 Qe5+ Kf8 Qb8+ Kg7 Qe5+ f6 Qe7+ Kh6 Qf8+ Kg5 h4+ Kh5 Qc5+ f5 Qc1 Rxg2+ Kh3 Rh2+ Kg3 Rag2+ Kf3 Rg4 Qd1 Rhxh4 Kf2 Rh2+ Kf3 Rh3+ Ke2 Rg2+ Kf1+ Rg4 Kf2 g5 Qd8 h6 Qe8+ Kh4 Kf1 h5 Qe1+ Rhg3 Qe5 f4 Qe1 f3 Kf2 Rf4 Qh1+ Rh3 Qe1 g4", + "players": [ + { + "color": "white", + "name": "borska (2013)", + "userId": "borska" + }, + { + "color": "black", + "name": "Xxn00bkillar69xX (1990)", + "userId": "xxn00bkillar69xx" + } + ], + "rated": true + }, + "puzzle": { + "id": "K69di", + "initialPly": 123, + "plays": 1970, + "rating": 2022, + "solution": [ + "e1e7", + "f4f6", + "e7f6" + ], + "themes": [ + "short", + "queenRookEndgame", + "endgame", + "mateIn2" + ] + } + } + }, + "PuzzleRoundJson": { + "type": "object", + "properties": { + "id": { + "type": "string", + "example": "BwPiW" + }, + "date": { + "type": "number", + "example": 1514505150384 + }, + "win": { + "type": "boolean", + "example": true + }, + "puzzleRating": { + "type": "number", + "example": 1877 + } + } + }, + "PuzzleDashboardJson": { + "example": { + "days": 30, + "global": { + "firstWins": 276, + "nb": 501, + "performance": 1570, + "puzzleRatingAvg": 1523, + "replayWins": 2 + }, + "themes": { + "advancedPawn": { + "results": { + "firstWins": 19, + "nb": 39, + "performance": 1438, + "puzzleRatingAvg": 1476, + "replayWins": 1 + }, + "theme": "Advanced pawn" + }, + "anastasiaMate": { + "results": { + "firstWins": 5, + "nb": 6, + "performance": 1720, + "puzzleRatingAvg": 1387, + "replayWins": 0 + }, + "theme": "Anastasia's mate" + } + } + } + }, + "PuzzleRaceJson": { + "example": { + "id": "Kj1t0", + "url": "https://lichess.org/racer/Kj1t0" + } + }, + "StormDashboardJson": { + "example": { + "high": { + "allTime": 11, + "day": 0, + "month": 7, + "week": 0 + }, + "days": [ + { + "_id": "2021/1/28", + "combo": 8, + "errors": 1, + "highest": 1084, + "moves": 9, + "runs": 26, + "score": 4, + "time": 175 + }, + { + "_id": "2021/1/27", + "combo": 14, + "errors": 1, + "highest": 1095, + "moves": 15, + "runs": 15, + "score": 7, + "time": 23 + }, + { + "_id": "2021/1/22", + "combo": 14, + "errors": 1, + "highest": 1095, + "moves": 15, + "runs": 15, + "score": 3, + "time": 23 + } + ] + } + }, + "RatingHistory": { + "example": [ + { + "name": "Bullet", + "points": [ + [ + 2011, + 0, + 8, + 1472 + ], + [ + 2011, + 0, + 9, + 1332 + ], + [ + 2011, + 8, + 12, + 1314 + ] + ] + }, + { + "name": "Blitz", + "points": [ + [ + 2011, + 7, + 29, + 1332 + ] + ] + } + ] + }, + "PerfStat": { + "example": { + "perf": { + "glicko": { + "rating": 1672.42, + "deviation": 45.13, + "provisional": false + }, + "nb": 5692, + "progress": -27 + }, + "rank": 98121, + "percentile": 69.7, + "stat": { + "perfType": { + "key": "bullet", + "name": "Bullet" + }, + "highest": { + "int": 1902, + "at": "2021-05-31T08:58:53.701Z", + "gameId": "YEDqtwig" + }, + "lowest": { + "int": 1417, + "at": "2016-06-28T13:54:39.656Z", + "gameId": "rNM4J1GJ" + }, + "bestWins": { + "results": [ + { + "opInt": 2238, + "opId": { + "id": "hyperdragon84", + "name": "HyperDragon84" + }, + "at": "2019-06-19T17:09:05.187Z", + "gameId": "DGB53z9w" + }, + { + "opInt": 2089, + "opId": { + "id": "osipov", + "name": "osipov" + }, + "at": "2017-06-18T09:46:05.016Z", + "gameId": "gurRhuMi" + }, + { + "opInt": 2071, + "opId": { + "id": "spark50", + "name": "Spark50" + }, + "at": "2020-07-04T08:36:12.948Z", + "gameId": "a93Dk1mv" + }, + { + "opInt": 2045, + "opId": { + "id": "yasha43", + "name": "Yasha43" + }, + "at": "2021-05-17T14:01:41.098Z", + "gameId": "j3jZnGTr" + }, + { + "opInt": 2034, + "opId": { + "id": "midedu", + "name": "midedu" + }, + "at": "2020-06-27T17:32:47.001Z", + "gameId": "OiaMVLQ8" + } + ] + }, + "worstLosses": { + "results": [ + { + "opInt": 1186, + "opId": { + "id": "happy0", + "name": "Happy0" + }, + "at": "2016-07-07T19:48:29.077Z", + "gameId": "Q01bbiN4" + }, + { + "opInt": 1197, + "opId": { + "id": "kazmankiller86", + "name": "KazmanKiller86" + }, + "at": "2016-10-16T14:21:37.748Z", + "gameId": "Aivqh9Sp" + }, + { + "opInt": 1201, + "opId": { + "id": "artem555", + "name": "artem555" + }, + "at": "2016-08-28T16:21:30.923Z", + "gameId": "tiRAbhnX" + }, + { + "opInt": 1265, + "opId": { + "id": "arcenuu", + "name": "Arcenuu" + }, + "at": "2016-12-24T14:28:03.866Z", + "gameId": "A68wUOoh" + }, + { + "opInt": 1283, + "opId": { + "id": "amritalib76", + "name": "Amritalib76" + }, + "at": "2018-06-26T09:55:39.354Z", + "gameId": "sbNVikmo" + } + ] + }, + "count": { + "all": 5858, + "rated": 5688, + "win": 2789, + "loss": 2806, + "draw": 263, + "tour": 654, + "berserk": 1, + "opAvg": 1671.44, + "seconds": 784886, + "disconnects": 0 + }, + "resultStreak": { + "win": { + "cur": { + "v": 0 + }, + "max": { + "v": 11, + "from": { + "at": "2021-06-14T15:38:50.681Z", + "gameId": "wTX2IExo" + }, + "to": { + "at": "2021-06-15T18:41:46.970Z", + "gameId": "1z4rrjgw" + } + } + }, + "loss": { + "cur": { + "v": 3, + "from": { + "at": "2021-06-29T17:53:23.642Z", + "gameId": "pfcnjgik" + }, + "to": { + "at": "2021-06-29T18:04:48.358Z", + "gameId": "6sPaGL8T" + } + }, + "max": { + "v": 14, + "from": { + "at": "2018-06-11T14:43:39.296Z", + "gameId": "1fc9dqun" + }, + "to": { + "at": "2018-06-11T15:10:30.908Z", + "gameId": "Nzy6UgwY" + } + } + } + }, + "playStreak": { + "nb": { + "cur": { + "v": 0 + }, + "max": { + "v": 118, + "from": { + "at": "2018-06-11T10:32:21.248Z", + "gameId": "UAsNnJbN" + }, + "to": { + "at": "2018-06-11T15:13:01.193Z", + "gameId": "T7fHRaFG" + } + } + }, + "time": { + "cur": { + "v": 0 + }, + "max": { + "v": 12683, + "from": { + "at": "2018-06-12T14:11:14.021Z", + "gameId": "IrZCAW58" + }, + "to": { + "at": "2018-06-12T18:02:57.010Z", + "gameId": "RNF1mQ68" + } + } + }, + "lastDate": "2021-06-29T18:04:48.358Z" + } + } + } + }, + "Top10s": { + "example": { + "bullet": [ + { + "id": "bahadirozen", + "username": "BahadirOzen", + "perfs": { + "bullet": { + "rating": 3018, + "progress": 18 + } + }, + "online": true, + "title": "FM" + }, + { + "id": "penguingim1", + "username": "penguingim1", + "perfs": { + "bullet": { + "rating": 2983, + "progress": -36 + } + }, + "title": "GM", + "online": true, + "patron": true + }, + { + "id": "night-king96", + "username": "Night-King96", + "perfs": { + "bullet": { + "rating": 2958, + "progress": 35 + } + }, + "title": "GM" + } + ], + "blitz": [], + "rapid": [], + "classical": [], + "ultraBullet": [], + "chess960": [], + "crazyhouse": [], + "antichess": [], + "atomic": [], + "horde": [], + "kingOfTheHill": [], + "racingKings": [], + "threeCheck": [] + } + }, + "Leaderboard": { + "example": { + "users": [ + { + "id": "bahadirozen", + "username": "BahadirOzen", + "perfs": { + "bullet": { + "rating": 3018, + "progress": 18 + } + }, + "online": true, + "title": "FM" + }, + { + "id": "penguingim1", + "username": "penguingim1", + "perfs": { + "bullet": { + "rating": 2983, + "progress": -36 + } + }, + "title": "GM", + "online": true, + "patron": true + }, + { + "id": "night-king96", + "username": "Night-King96", + "perfs": { + "bullet": { + "rating": 2958, + "progress": 35 + } + }, + "title": "GM" + } + ] + } + }, + "UserPreferences": { + "type": "object", + "properties": { + "dark": { + "type": "boolean", + "example": true + }, + "transp": { + "type": "boolean", + "example": false + }, + "bgImg": { + "type": "string", + "format": "uri" + }, + "is3d": { + "type": "boolean", + "example": false + }, + "theme": { + "type": "string", + "enum": [ + "blue", + "blue2", + "blue3", + "blue-marble", + "canvas", + "wood", + "wood2", + "wood3", + "wood4", + "maple", + "maple2", + "brown", + "leather", + "green", + "marble", + "green-plastic", + "grey", + "metal", + "olive", + "newspaper", + "purple", + "purple-diag", + "pink", + "ic" + ] + }, + "pieceSet": { + "type": "string", + "enum": [ + "cburnett", + "merida", + "alpha", + "pirouetti", + "chessnut", + "chess7", + "reillycraig", + "companion", + "riohacha", + "kosal", + "leipzig", + "fantasy", + "spatial", + "california", + "pixel", + "maestro", + "fresca", + "cardinal", + "gioco", + "tatiana", + "staunty", + "governor", + "dubrovny", + "icpieces", + "shapes", + "letter" + ] + }, + "theme3d": { + "type": "string", + "enum": [ + "Black-White-Aluminium", + "Brushed-Aluminium", + "China-Blue", + "China-Green", + "China-Grey", + "China-Scarlet", + "Classic-Blue", + "Gold-Silver", + "Light-Wood", + "Power-Coated", + "Rosewood", + "Marble", + "Wax", + "Jade", + "Woodi" + ] + }, + "pieceSet3d": { + "type": "string", + "enum": [ + "Basic", + "Wood", + "Metal", + "RedVBlue", + "ModernJade", + "ModernWood", + "Glass", + "Trimmed", + "Experimental", + "Staunton", + "CubesAndPi" + ] + }, + "soundSet": { + "type": "string", + "enum": [ + "silent", + "standard", + "piano", + "nes", + "sfx", + "futuristic", + "robot", + "music", + "speech" + ] + }, + "blindfold": { + "type": "integer", + "example": 0 + }, + "autoQueen": { + "type": "integer", + "example": 2 + }, + "autoThreefold": { + "type": "integer", + "example": 2 + }, + "takeback": { + "type": "integer", + "example": 3 + }, + "moretime": { + "type": "integer", + "example": 3 + }, + "clockTenths": { + "type": "integer", + "example": 1 + }, + "clockBar": { + "type": "boolean", + "example": true + }, + "clockSound": { + "type": "boolean", + "example": true + }, + "premove": { + "type": "boolean", + "example": true + }, + "animation": { + "type": "integer", + "example": 2 + }, + "captured": { + "type": "boolean", + "example": true + }, + "follow": { + "type": "boolean", + "example": true + }, + "highlight": { + "type": "boolean", + "example": true + }, + "destination": { + "type": "boolean", + "example": true + }, + "coords": { + "type": "integer", + "example": 2 + }, + "replay": { + "type": "integer", + "example": 2 + }, + "challenge": { + "type": "integer", + "example": 4 + }, + "message": { + "type": "integer", + "example": 3 + }, + "coordColor": { + "type": "integer", + "example": 2 + }, + "submitMove": { + "type": "integer", + "example": 4 + }, + "confirmResign": { + "type": "integer", + "example": 1 + }, + "insightShare": { + "type": "integer", + "example": 1 + }, + "keyboardMove": { + "type": "integer", + "example": 0 + }, + "zen": { + "type": "integer", + "example": 0 + }, + "moveEvent": { + "type": "integer", + "example": 2 + }, + "rookCastle": { + "type": "integer", + "example": 1 + } + } + }, + "ArenaTournaments": { + "type": "object", + "properties": { + "created": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ArenaTournament" + } + }, + "started": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ArenaTournament" + } + }, + "finished": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ArenaTournament" + } + } + } + }, + "ArenaTournament": { + "example": { + "id": "QITRjufu", + "fullName": "U1700 SuperBlitz Arena", + "rated": true, + "clock": { + "increment": 0, + "limit": 180 + }, + "minutes": 57, + "createdBy": "lichess", + "system": "arena", + "secondsToStart": 0, + "secondsToFinish": 36000, + "isFinished": true, + "isRecentlyFinished": true, + "pairingsClosed": true, + "startsAt": 1522803600000, + "nbPlayers": 154, + "perf": { + "icon": ")", + "key": "blitz", + "name": "Blitz", + "position": 1 + }, + "schedule": { + "freq": "hourly", + "speed": "superblitz" + }, + "variant": { + "key": "standard", + "name": "Standard", + "short": "Std" + }, + "duels": [ + { + "id": "0MM6q4tQ", + "p": [ + { + "n": "player1", + "r": 1500, + "k": 3 + }, + { + "n": "player2", + "r": 1500, + "k": 3 + } + ] + } + ], + "standings": { + "page": 1, + "players": [ + { + "name": "player1", + "rank": 1, + "rating": 1500, + "score": 3, + "sheet": { + "scores": "220422102202", + "fire": true + } + } + ] + }, + "featured": { + "id": "khe72Fer", + "fen": "rn1qkb1r/pQ3ppp/2b2n2/8/5P2/4P3/PP4PP/RNB1KBNR", + "color": "black", + "lastMove": "d7c6", + "white": { + "rank": 2, + "name": "player1", + "rating": 1360 + }, + "black": { + "rank": 5, + "name": "player2", + "rating": 1431 + } + }, + "podium": [ + { + "name": "player1", + "rank": 1, + "rating": 1500, + "score": 3, + "nb": { + "game": 3, + "beserk": 0, + "win": 2 + }, + "performance": 1787 + } + ], + "stats": { + "games": 454, + "moves": 27542, + "whiteWins": 236, + "blackWins": 207, + "draws": 11, + "berserks": 0, + "averageRating": 1320 + } + } + }, + "ArenaTournamentVariantIsKey": { + "example": { + "id": "QITRjufu", + "fullName": "U1700 SuperBlitz Arena", + "rated": true, + "clock": { + "increment": 0, + "limit": 180 + }, + "minutes": 57, + "createdBy": "lichess", + "system": "arena", + "secondsToStart": 0, + "secondsToFinish": 36000, + "isFinished": true, + "isRecentlyFinished": true, + "pairingsClosed": true, + "startsAt": 1522803600000, + "nbPlayers": 154, + "perf": { + "icon": ")", + "key": "blitz", + "name": "Blitz", + "position": 1 + }, + "schedule": { + "freq": "hourly", + "speed": "superblitz" + }, + "variant": "standard", + "duels": [ + { + "id": "0MM6q4tQ", + "p": [ + { + "n": "player1", + "r": 1500, + "k": 3 + }, + { + "n": "player2", + "r": 1500, + "k": 3 + } + ] + } + ], + "standings": { + "page": 1, + "players": [ + { + "name": "player1", + "rank": 1, + "rating": 1500, + "score": 3, + "sheet": { + "scores": [ + { + "0": 2, + "1": 2 + }, + { + "0": 4, + "1": 3 + }, + 0 + ], + "total": 6, + "fire": true + } + } + ] + }, + "featured": { + "id": "khe72Fer", + "fen": "rn1qkb1r/pQ3ppp/2b2n2/8/5P2/4P3/PP4PP/RNB1KBNR", + "color": "black", + "lastMove": "d7c6", + "white": { + "rank": 2, + "name": "player1", + "rating": 1360 + }, + "black": { + "rank": 5, + "name": "player2", + "rating": 1431 + } + }, + "podium": [ + { + "name": "player1", + "rank": 1, + "rating": 1500, + "score": 3, + "sheet": { + "scores": [ + { + "0": 2, + "1": 2 + }, + { + "0": 4, + "1": 3 + }, + 0 + ], + "total": 6, + "fire": true + }, + "nb": { + "game": 3, + "beserk": 0, + "win": 2 + }, + "performance": 1787 + } + ], + "stats": { + "games": 454, + "moves": 27542, + "whiteWins": 236, + "blackWins": 207, + "draws": 11, + "berserks": 0, + "averageRating": 1320 + } + } + }, + "SwissTournament": { + "example": { + "rated": true, + "clock": { + "increment": 0, + "limit": 300 + }, + "createdBy": "thibault", + "id": "ZmKWCOye", + "name": "Wang", + "nbOngoing": 0, + "nbPlayers": 0, + "nbRounds": 2, + "nextRound": { + "at": "2020-05-11T12:23:18.233-06:00", + "in": 600 + }, + "round": 0, + "startsAt": "2020-05-11T12:23:18.233-06:00", + "status": "created", + "variant": "standard", + "isRecentlyFinished": false, + "password": true, + "stats": { + "absences": 1608, + "averageRating": 1588, + "blackWins": 42541, + "byes": 12, + "draws": 0, + "games": 42689, + "whiteWins": 42837 + } + } + }, + "Simul": { + "example": { + "id": "pDGbxhUe", + "name": "GM ChessWeeb", + "fullName": "GM ChessWeeb simul", + "host": { + "id": "chessweeb", + "name": "ChessWeeb", + "rating": 1500, + "title": "GM" + }, + "isCreated": false, + "isFinished": true, + "isRunning": false, + "estimatedStartAt": 1620029815106, + "startedAt": 1620029815106, + "finishedAt": 1620029937283, + "nbApplicants": 0, + "nbPairings": 24, + "text": "", + "variants": [ + { + "icon": "+", + "key": "standard", + "name": "Standard" + } + ] + } + }, + "BroadcastTour": { + "example": { + "tour": { + "description": "Match for 1st 2nd and 3rd place.", + "id": "QYiOYnl1", + "name": "New in Chess Classic | Finals", + "slug": "new-in-chess-classic--finals", + "url": "https://lichess.org/broadcast/new-in-chess-classic--finals/phgcXuBl" + }, + "rounds": [ + { + "id": "BueO56UJ", + "name": "Finals Day 1", + "slug": "finals-day-1", + "url": "https://lichess.org/broadcast/new-in-chess-classic--finals/finals-day-1/BueO56UJ" + }, + { + "id": "yeGGfkfY", + "name": "Finals Day 2", + "slug": "finals-day-2", + "url": "https://lichess.org/broadcast/new-in-chess-classic--finals/finals-day-2/yeGGfkfY" + } + ] + } + }, + "BroadcastRound": { + "example": { + "id": "BueO56UJ", + "name": "Finals Day 1", + "slug": "finals-day-1", + "url": "https://lichess.org/broadcast/new-in-chess-classic--finals/finals-day-1/BueO56UJ", + "games": [ + { + "id": "GRjidNTw", + "name": "Martin Fargac - Vit Kostka", + "ongoing": true, + "res": "*", + "url": "http://l.org/broadcast/isreali-championship/round-4/iCEwAzEX/GRjidNTw" + }, + { + "id": "81TcKCWT", + "name": "Pavel Zabystrzan - Kilian Slovak", + "res": "½-½", + "url": "http://l.org/broadcast/isreali-championship/round-4/iCEwAzEX/tJpK7gbl" + }, + { + "id": "xEfufedI", + "name": "Roman Pilch - Bartolomej Buchta", + "res": "1-0", + "url": "http://l.org/broadcast/isreali-championship/round-4/iCEwAzEX/xEfufedI" + } + ] + } + }, + "OpeningExplorerJson": { + "example": { + "white": 1443, + "draws": 3787, + "black": 1156, + "moves": [ + { + "uci": "c6d5", + "san": "cxd5", + "averageRating": 2423, + "white": 1443, + "draws": 3787, + "black": 1155, + "game": null + }, + { + "uci": "g8f6", + "san": "Nf6", + "averageRating": 2515, + "white": 0, + "draws": 0, + "black": 1, + "game": { + "id": "1EErB5jc", + "winner": "black", + "white": { + "name": "Drozdovskij, Yuri", + "rating": 2509 + }, + "black": { + "name": "Dobrov, Vladimir", + "rating": 2515 + }, + "year": 2006, + "month": "2006-01" + } + } + ], + "topGames": [ + { + "uci": "c6d5", + "id": "kN6d9l2i", + "winner": "black", + "white": { + "name": "Carlsen, M.", + "rating": 2881 + }, + "black": { + "name": "Anand, V.", + "rating": 2785 + }, + "year": 2014, + "month": "2014-06" + }, + { + "uci": "c6d5", + "id": "qeYPJL2y", + "winner": "white", + "white": { + "name": "So, W.", + "rating": 2778 + }, + "black": { + "name": "Carlsen, M.", + "rating": 2843 + }, + "year": 2018, + "month": "2018-06" + } + ], + "recentGames": [], + "opening": { + "eco": "D10", + "name": "Slav Defense: Exchange Variation" + } + } + }, + "OpeningExplorerPlayerJson": { + "example": { + "white": 359, + "draws": 23, + "black": 273, + "moves": [ + { + "uci": "c2c4", + "san": "c4", + "averageOpponentRating": 1695, + "performance": 1744, + "white": 354, + "draws": 23, + "black": 266, + "game": null + }, + { + "uci": "c2c3", + "san": "c3", + "averageOpponentRating": 1796, + "performance": 1796, + "white": 2, + "draws": 0, + "black": 2, + "game": null + }, + { + "uci": "e2e4", + "san": "e4", + "averageOpponentRating": 1762, + "performance": 1640, + "white": 1, + "draws": 0, + "black": 2, + "game": null + }, + { + "uci": "g1f3", + "san": "Nf3", + "averageOpponentRating": 1496, + "performance": 1374, + "white": 1, + "draws": 0, + "black": 2, + "game": null + }, + { + "uci": "h2h3", + "san": "h3", + "averageOpponentRating": 1696, + "performance": 2496, + "white": 1, + "draws": 0, + "black": 0, + "game": { + "id": "zyI4GGKv", + "winner": "white", + "speed": "bullet", + "mode": "rated", + "black": { + "name": "gocool99", + "rating": 1696 + }, + "white": { + "name": "revoof", + "rating": 1702 + }, + "year": 2020, + "month": "2020-07" + } + }, + { + "uci": "h2h4", + "san": "h4", + "averageOpponentRating": 1674, + "performance": 874, + "white": 0, + "draws": 0, + "black": 1, + "game": { + "id": "9vA24xBn", + "winner": "black", + "speed": "bullet", + "mode": "rated", + "black": { + "name": "MentalBlood", + "rating": 1674 + }, + "white": { + "name": "revoof", + "rating": 1657 + }, + "year": 2020, + "month": "2020-06" + } + } + ], + "recentGames": [ + { + "uci": "c2c4", + "id": "BGLmUtv7", + "winner": "white", + "speed": "bullet", + "mode": "rated", + "black": { + "name": "yigithanyiigit", + "rating": 1227 + }, + "white": { + "name": "revoof", + "rating": 1717 + }, + "year": 2022, + "month": "2022-03" + } + ], + "opening": { + "eco": "D00", + "name": "Queen's Pawn Game" + }, + "queuePosition": 0 + } + }, + "TablebaseJson": { + "type": "object", + "properties": { + "category": { + "type": "string", + "enum": [ + "win", + "unknown", + "maybe-win", + "cursed-win", + "draw", + "blessed-loss", + "maybe-loss", + "loss" + ], + "description": "`cursed-win` and `blessed-loss` means the 50-move rule prevents\nthe decisive result.\n\n`maybe-win` and `maybe-loss` means exact result is unknown due to\n[DTZ rounding](https://syzygy-tables.info/metrics#dtz), i.e., the\nwin or loss could also be prevented by the 50-move rule if\nthe user has deviated from the tablebase recommendation since the\nlast pawn move or capture.\n" + }, + "dtz": { + "type": "integer", + "description": "[DTZ50'' with rounding](https://syzygy-tables.info/metrics#dtz) or null if unknown\n" + }, + "precise_dtz": { + "type": "integer", + "description": "DTZ50'' (only if guaranteed to be not rounded) or null if unknown\n" + }, + "dtm": { + "type": "integer", + "description": "Distance to mate (only for positions with not more than 5 pieces)" + }, + "checkmate": { + "type": "boolean" + }, + "stalemate": { + "type": "boolean" + }, + "variant_win": { + "type": "boolean", + "description": "Only in chess variants" + }, + "variant_loss": { + "type": "boolean", + "description": "Only in chess variants" + }, + "insufficient_material": { + "type": "boolean" + }, + "moves": { + "type": "array", + "description": "Information about legal moves, best first", + "items": { + "$ref": "#/components/schemas/Move" + } + } + }, + "example": { + "dtz": 1, + "precise_dtz": 1, + "dtm": 17, + "checkmate": false, + "stalemate": false, + "variant_win": false, + "variant_loss": false, + "insufficient_material": false, + "category": "win", + "moves": [ + { + "uci": "h7h8q", + "san": "h8=Q+", + "dtz": -2, + "precise_dtz": -2, + "dtm": -16, + "zeroing": true, + "checkmate": false, + "stalemate": false, + "variant_win": false, + "variant_loss": false, + "insufficient_material": false, + "category": "loss" + } + ] + } + }, + "Move": { + "type": "object", + "properties": { + "uci": { + "type": "string", + "example": "h7h8q" + }, + "san": { + "type": "string", + "example": "h8=Q+" + }, + "category": { + "type": "string", + "enum": [ + "loss", + "unknown", + "maybe-loss", + "blessed-loss", + "draw", + "cursed-win", + "maybe-win", + "win" + ] + }, + "dtz": { + "type": "integer", + "description": "DTZ50'' with rounding or null if unknown" + }, + "precise_dtz": { + "type": "integer", + "description": "DTZ50'' (only if guaranteed to be not rounded) or null if unknown\n" + }, + "dtm": { + "type": "integer", + "description": "Distance to mate (only for positions with not more than 5 pieces)" + }, + "zeroing": { + "type": "boolean" + }, + "checkmate": { + "type": "boolean" + }, + "stalemate": { + "type": "boolean" + }, + "variant_win": { + "type": "boolean" + }, + "variant_loss": { + "type": "boolean" + }, + "insufficient_material": { + "type": "boolean" + } + } + }, + "Team": { + "type": "object", + "properties": { + "id": { + "type": "string", + "example": "coders" + }, + "name": { + "type": "string", + "example": "Coders" + }, + "description": { + "type": "string", + "example": "There are 10 kinds of people in the world: those who understand binary, and the others.\r\n\r\nIf you want to join the team, prove (briefly) that you can code in the request message!" + }, + "open": { + "type": "boolean", + "example": false + }, + "leader": { + "$ref": "#/components/schemas/LightUser" + }, + "leaders": { + "type": "array", + "items": { + "$ref": "#/components/schemas/LightUser" + } + }, + "nbMembers": { + "type": "integer", + "example": 3129 + }, + "location": { + "type": [ + "string", + "null" + ], + "example": "Planet Earth" + } + } + }, + "TeamRequest": { + "type": "object", + "properties": { + "teamId": { + "type": "string", + "example": "coders" + }, + "userId": { + "type": "string", + "example": "thibault" + }, + "date": { + "type": "number", + "example": 1514505150384 + }, + "message": { + "type": "string", + "example": "Hello, I would like to join the team!" + } + } + }, + "TeamRequestWithUser": { + "type": "object", + "properties": { + "request": { + "$ref": "#/components/schemas/TeamRequest" + }, + "user": { + "$ref": "#/components/schemas/User" + } + } + }, + "GameEventPlayer": { + "type": "object", + "properties": { + "aiLevel": { + "type": "number" + }, + "id": { + "type": "string" + }, + "name": { + "type": "string" + }, + "rating": { + "type": "number" + }, + "provisional": { + "type": "boolean" + } + } + }, + "GameFullEvent": { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "gameFull" + }, + "id": { + "type": "string" + }, + "variant": { + "$ref": "#/components/schemas/Variant" + }, + "clock": { + "oneOf": [ + { + "$ref": "#/components/schemas/Clock" + }, + { + "type": "null" + } + ] + }, + "speed": { + "$ref": "#/components/schemas/Speed" + }, + "perf": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Translated perf name (e.g. \"Classical\" or \"Blitz\")" + } + } + }, + "rated": { + "type": "boolean" + }, + "createdAt": { + "type": "number", + "format": "int64" + }, + "white": { + "$ref": "#/components/schemas/GameEventPlayer" + }, + "black": { + "$ref": "#/components/schemas/GameEventPlayer" + }, + "initialFen": { + "type": "string", + "default": "startpos" + }, + "state": { + "$ref": "#/components/schemas/GameStateEvent" + }, + "tournamentId": { + "type": "string" + } + }, + "required": [ + "type", + "id", + "variant", + "clock", + "speed", + "perf", + "rated", + "createdAt", + "white", + "black", + "initialFen", + "state" + ] + }, + "GameStateEvent": { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "gameState" + }, + "moves": { + "type": "string", + "description": "Current moves in UCI format" + }, + "wtime": { + "type": "integer", + "description": "Integer of milliseconds White has left on the clock" + }, + "btime": { + "type": "integer", + "description": "Integer of milliseconds Black has left on the clock" + }, + "winc": { + "type": "integer", + "description": "Integer of White Fisher increment." + }, + "binc": { + "type": "integer", + "description": "Integer of Black Fisher increment." + }, + "status": { + "$ref": "#/components/schemas/GameStatus" + }, + "winner": { + "type": "string", + "description": "Color of the winner, if any" + }, + "wdraw": { + "type": "boolean", + "description": "true if white is offering draw, else omitted" + }, + "bdraw": { + "type": "boolean", + "description": "true if black is offering draw, else omitted" + }, + "wtakeback": { + "type": "boolean", + "description": "true if white is proposing takeback, else omitted" + }, + "btakeback": { + "type": "boolean", + "description": "true if black is proposing takeback, else omitted" + } + }, + "required": [ + "type", + "moves", + "wtime", + "btime", + "winc", + "binc", + "status" + ] + }, + "ChatLineEvent": { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "chatLine" + }, + "room": { + "type": "string", + "enum": [ + "player", + "spectator" + ] + }, + "username": { + "type": "string" + }, + "text": { + "type": "string" + } + }, + "required": [ + "type", + "room", + "username", + "text" + ] + }, + "OpponentGone": { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "opponentGone" + }, + "gone": { + "type": "boolean" + }, + "claimWinInSeconds": { + "type": "number" + } + }, + "required": [ + "type", + "gone" + ] + }, + "GameEventInfo": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "source": { + "type": "string", + "enum": [ + "lobby", + "friend", + "ai", + "api", + "tournament", + "position", + "import", + "importlive", + "simul", + "relay", + "pool", + "swiss" + ] + }, + "status": { + "$ref": "#/components/schemas/GameStatus" + }, + "winner": { + "type": "string", + "enum": [ + "white", + "black" + ] + }, + "compat": { + "type": "object", + "properties": { + "bot": { + "type": "boolean" + }, + "board": { + "type": "boolean" + } + } + } + } + }, + "GameStartEvent": { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "gameStart" + }, + "game": { + "$ref": "#/components/schemas/GameEventInfo" + } + } + }, + "GameFinishEvent": { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "gameFinish" + }, + "game": { + "$ref": "#/components/schemas/GameEventInfo" + } + } + }, + "ChallengeEvent": { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "challenge" + }, + "challenge": { + "$ref": "#/components/schemas/ChallengeJson" + } + } + }, + "ChallengeCanceledEvent": { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "challengeCanceled" + }, + "challenge": { + "$ref": "#/components/schemas/ChallengeJson" + } + } + }, + "ChallengeDeclinedEvent": { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "challengeDeclined" + }, + "challenge": { + "$ref": "#/components/schemas/ChallengeCanceledJson" + } + } + }, + "Ok": { + "properties": { + "ok": { + "type": "boolean" + } + }, + "example": { + "ok": true + } + }, + "Error": { + "properties": { + "error": { + "type": "string", + "description": "The cause of the error." + } + }, + "example": { + "error": "This request is invalid because [...]" + } + }, + "OAuthError": { + "properties": { + "error": { + "type": "string", + "description": "The cause of the error." + }, + "error_description": { + "type": "string", + "description": "The reason why the request was rejected." + } + }, + "example": { + "error": "invalid_grant", + "error_description": "hash of code_verifier does not match code_challenge" + } + }, + "NotFound": { + "properties": { + "error": { + "type": "string" + } + }, + "example": { + "error": "Not found." + } + }, + "SwissUnauthorisedEdit": { + "properties": { + "error": { + "type": "string" + } + }, + "example": { + "error": "This user cannot edit this swiss" + } + }, + "GameStream": { + "example": [ + { + "id": "A5fcMO3k", + "rated": true, + "variant": "standard", + "speed": "bullet", + "perf": "bullet", + "createdAt": 1525789431889, + "status": 20, + "statusName": "started", + "clock": { + "initial": 60, + "increment": 0, + "totalTime": 60 + }, + "players": { + "white": { + "userId": "kastorcito", + "rating": 2617 + }, + "black": { + "userId": "er_or", + "rating": 2288 + } + } + } + ] + }, + "MoveStream": { + "example": [ + { + "id": "LuGQwhBb", + "variant": { + "key": "standard", + "name": "Standard", + "short": "Std" + }, + "speed": "blitz", + "perf": "blitz", + "rated": true, + "initialFen": "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1", + "fen": "rnbqkb1r/1p1ppppp/p6n/2p4Q/8/1P2P3/P1PP1PPP/RNB1KBNR w KQkq - 0 4", + "player": "white", + "turns": 6, + "startedAtTurn": 0, + "source": "pool", + "status": { + "id": 20, + "name": "started" + }, + "createdAt": 1620029815106, + "lastMove": "c7c5", + "players": { + "white": { + "user": { + "name": "ARM-777777", + "title": "GM", + "id": "arm-777777" + }, + "rating": 3120 + }, + "black": { + "user": { + "name": "Flash_Marafon", + "id": "flash_marafon" + }, + "rating": 3015 + } + } + }, + { + "fen": "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w", + "wc": 180, + "bc": 180 + }, + { + "fen": "rnbqkbnr/pppppppp/8/8/8/4P3/PPPP1PPP/RNBQKBNR b", + "lm": "e2e3", + "wc": 180, + "bc": 180 + }, + { + "fen": "rnbqkb1r/pppppppp/7n/8/8/4P3/PPPP1PPP/RNBQKBNR w", + "lm": "g8h6", + "wc": 180, + "bc": 180 + }, + { + "fen": "rnbqkb1r/pppppppp/7n/8/8/1P2P3/P1PP1PPP/RNBQKBNR b", + "lm": "b2b3", + "wc": 177, + "bc": 180 + }, + { + "fen": "rnbqkb1r/1ppppppp/p6n/8/8/1P2P3/P1PP1PPP/RNBQKBNR w", + "lm": "a7a6", + "wc": 177, + "bc": 177 + } + ] + }, + "ExternalEngineRegistration": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Display name of the engine.", + "example": "Stockfish 15", + "minLength": 3, + "maxLength": 200 + }, + "maxThreads": { + "type": "integer", + "description": "Maximum number of available threads.", + "example": 8, + "minimum": 1, + "maximum": 65536 + }, + "maxHash": { + "type": "integer", + "description": "Maximum available hash table size, in MiB.", + "example": 2048, + "minimum": 1, + "maximum": 1048576 + }, + "defaultDepth": { + "type": "integer", + "description": "Estimated depth of normal search.", + "example": 24, + "minimum": 0, + "maximum": 246 + }, + "variants": { + "type": "array", + "description": "Optional list of supported chess variants.", + "items": { + "$ref": "#/components/schemas/UciVariant" + } + }, + "providerSecret": { + "type": "string", + "description": "A random token that can be used to\n[wait for analysis requests](#tag/External-engine/operation/apiExternalEngineAcquire)\nand provide analysis.\n\nThe engine provider should securely generate a random string.\n\nThe token will not be readable again, even by the user.\n\nThe analysis provider can register multiple engines with the same\ntoken, even for different users, and wait for analysis requests\nfrom any of them. In this case, the request must not be made via\nCORS, so that the token is not revealed to any of the users.\n", + "example": "Dee3uwieZei9ahpaici9bee2yahsai0K", + "minLength": 16, + "maxLength": 1024 + }, + "providerData": { + "type": "string", + "description": "Arbitrary data that the engine provider can use for identification\nor bookkeeping.\n\nUsers can read this information, but updating it requires knowing\nor changing the `providerSecret`.\n" + } + }, + "required": [ + "name", + "maxThreads", + "maxHash", + "defaultDepth", + "providerSecret" + ] + }, + "ExternalEngine": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique engine registration ID.", + "example": "eei_aTKImBJOnv6j" + }, + "name": { + "type": "string", + "description": "Display name of the engine.", + "example": "Stockfish 15", + "minLength": 3, + "maxLength": 200 + }, + "clientSecret": { + "type": "string", + "description": "A secret token that can be used to\n[*request* analysis](#tag/External-engine/operation/apiExternalEngineAnalyse)\nfrom this external engine.\n", + "example": "ees_mdF2hK0hlKGSPeC6" + }, + "userId": { + "type": "string", + "description": "The user this engine has been registered for.", + "example": "thibault" + }, + "maxThreads": { + "type": "integer", + "description": "Maximum number of available threads.", + "example": 8, + "minimum": 1, + "maximum": 65536 + }, + "maxHash": { + "type": "integer", + "description": "Maximum available hash table size, in MiB.", + "example": 2048, + "minimum": 1, + "maximum": 1048576 + }, + "defaultDepth": { + "type": "integer", + "description": "Estimated depth of normal search.", + "example": 24, + "minimum": 0, + "maximum": 246 + }, + "variants": { + "type": "array", + "description": "List of supported chess variants.", + "example": [ + "chess" + ], + "items": { + "$ref": "#/components/schemas/UciVariant" + } + }, + "providerData": { + "type": "string", + "description": "Arbitrary data that the engine provider can use for identification\nor bookkeeping.\n\nUsers can read this information, but updating it requires knowing\nor changing the `providerSecret`.\n" + } + }, + "required": [ + "id", + "clientSecret", + "userId", + "name", + "maxThreads", + "maxHash", + "defaultDepth", + "variants" + ] + }, + "ExternalEngineWork": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "Arbitary string that identifies the analysis session.\nProviders may wish to clear the hash table between sessions.\n", + "example": "abcd1234" + }, + "threads": { + "type": "integer", + "minimum": 1, + "description": "Number of threads to use for analysis.", + "example": 4 + }, + "hash": { + "type": "integer", + "minimum": 1, + "description": "Hash table size to use for analysis, in MiB.", + "example": 128 + }, + "infinite": { + "type": "boolean", + "description": "Request an infinite search (rather than roughly aiming for\n`defaultDepth`).\n", + "example": false + }, + "multiPv": { + "type": "integer", + "minimum": 1, + "maximum": 5, + "description": "Requested number of principal variations.", + "example": 1 + }, + "variant": { + "$ref": "#/components/schemas/UciVariant" + }, + "initialFen": { + "type": "string", + "description": "Initial position of the game.", + "example": "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1" + }, + "moves": { + "type": "array", + "description": "List of moves played from the initial position, in UCI notation.", + "items": { + "type": "string" + }, + "example": [ + "e2e4", + "g8f6" + ] + } + }, + "required": [ + "sessionId", + "threads", + "hash", + "multiPv", + "variant", + "initialFen", + "moves" + ] + } + }, + "securitySchemes": { + "OAuth2": { + "type": "oauth2", + "description": "Read [the introduction for how to make authenticated requests](#section/Introduction/Authentication).\n", + "flows": { + "authorizationCode": { + "authorizationUrl": "https://lichess.org/oauth", + "tokenUrl": "https://lichess.org/api/token", + "scopes": { + "preference:read": "Read your preferences", + "preference:write": "Write your preferences", + "email:read": "Read your email address", + "challenge:read": "Read incoming challenges", + "challenge:write": "Create, accept, decline challenges", + "challenge:bulk": "Create, delete, query bulk pairings", + "study:read": "Read private studies and broadcasts", + "study:write": "Create, update, delete studies and broadcasts", + "tournament:write": "Create tournaments", + "racer:write": "Create and join puzzle races", + "puzzle:read": "Read puzzle activity", + "team:read": "Read private team information", + "team:write": "Join, leave teams", + "team:lead": "Manage teams (kick members, send PMs)", + "follow:read": "Read followed players", + "follow:write": "Follow and unfollow other players", + "msg:write": "Send private messages to other players", + "board:play": "Play with the Board API", + "bot:play": "Play with the Bot API. Only for [Bot accounts](#operation/botAccountUpgrade)", + "web:mod": "Use moderator tools (within the bounds of your permissions)" + } + } + } + } + }, + "examples": { + "challenge": { + "value": { + "type": "challenge", + "challenge": { + "id": "7pGLxJ4F", + "url": "https://lichess.org/VU0nyvsW", + "status": "created", + "compat": { + "bot": false, + "board": true + }, + "challenger": { + "id": "lovlas", + "name": "Lovlas", + "title": "IM", + "rating": 2506, + "patron": true, + "online": true, + "lag": 24 + }, + "destUser": { + "id": "thibot", + "name": "thibot", + "rating": 1500, + "provisional": true, + "online": true, + "lag": 45 + }, + "variant": { + "key": "standard", + "name": "Standard", + "short": "Std" + }, + "rated": true, + "timeControl": { + "type": "clock", + "limit": 300, + "increment": 25, + "show": "5+25" + }, + "color": "random", + "speed": "rapid", + "perf": { + "icon": "#", + "name": "Rapid" + } + } + } + }, + "challengeCanceled": { + "value": { + "type": "challengeCanceled", + "challenge": { + "id": "7pGLxJ4F", + "url": "https://lichess.org/VU0nyvsW", + "status": "created", + "compat": { + "bot": false, + "board": true + }, + "challenger": { + "id": "lovlas", + "name": "Lovlas", + "title": "IM", + "rating": 2506, + "patron": true, + "online": true, + "lag": 24 + }, + "destUser": { + "id": "thibot", + "name": "thibot", + "rating": 1500, + "provisional": true, + "online": true, + "lag": 45 + }, + "variant": { + "key": "standard", + "name": "Standard", + "short": "Std" + }, + "rated": true, + "timeControl": { + "type": "clock", + "limit": 300, + "increment": 25, + "show": "5+25" + }, + "color": "random", + "speed": "rapid", + "perf": { + "icon": "#", + "name": "Rapid" + } + } + } + }, + "challengeDeclined": { + "value": { + "type": "challengeDeclined", + "challenge": { + "id": "7pGLxJ4F", + "url": "https://lichess.org/VU0nyvsW", + "status": "created", + "compat": { + "bot": false, + "board": true + }, + "challenger": { + "id": "lovlas", + "name": "Lovlas", + "title": "IM", + "rating": 2506, + "patron": true, + "online": true, + "lag": 24 + }, + "destUser": { + "id": "thibot", + "name": "thibot", + "title": null, + "rating": 1500, + "provisional": true, + "online": true, + "lag": 45 + }, + "variant": { + "key": "standard", + "name": "Standard", + "short": "Std" + }, + "rated": true, + "timeControl": { + "type": "clock", + "limit": 300, + "increment": 25, + "show": "5+25" + }, + "color": "random", + "speed": "rapid", + "perf": { + "icon": "#", + "name": "Rapid" + } + } + } + }, + "gameStart": { + "value": { + "type": "gameStart", + "game": { + "gameId": "rCRw1AuO", + "fullId": "rCRw1AuOvonq", + "color": "black", + "fen": "r1bqkbnr/pppp2pp/2n1pp2/8/8/3PP3/PPPB1PPP/RN1QKBNR w KQkq - 2 4", + "hasMoved": true, + "isMyTurn": false, + "lastMove": "b8c6", + "opponent": { + "id": "philippe", + "rating": 1790, + "username": "Philippe" + }, + "perf": "correspondence", + "rated": false, + "secondsLeft": 1209600, + "source": "friend", + "speed": "correspondence", + "variant": { + "key": "standard", + "name": "Standard" + }, + "compat": { + "bot": false, + "board": true + } + } + } + }, + "gameFinish": { + "value": { + "type": "gameFinish", + "game": { + "gameId": "rCRw1AuO", + "fullId": "rCRw1AuOvonq", + "color": "black", + "fen": "r1bqkbnr/pppp2pp/2n1pp2/8/8/3PP3/PPPB1PPP/RN1QKBNR w KQkq - 2 4", + "hasMoved": true, + "isMyTurn": false, + "lastMove": "b8c6", + "opponent": { + "id": "philippe", + "rating": 1790, + "username": "Philippe" + }, + "perf": "correspondence", + "rated": false, + "secondsLeft": 1209600, + "source": "friend", + "speed": "correspondence", + "variant": { + "key": "standard", + "name": "Standard" + }, + "compat": { + "bot": false, + "board": true + } + } + } + }, + "gameFull": { + "value": { + "type": "gameFull", + "id": "5IrD6Gzz", + "rated": true, + "variant": { + "key": "standard", + "name": "Standard", + "short": "Std" + }, + "clock": { + "initial": 1200000, + "increment": 10000 + }, + "speed": "classical", + "perf": { + "name": "Classical" + }, + "createdAt": 1523825103562, + "white": { + "id": "lovlas", + "name": "lovlas", + "provisional": false, + "rating": 2500, + "title": "IM" + }, + "black": { + "id": "leela", + "name": "leela", + "rating": 2390 + }, + "initialFen": "startpos", + "state": { + "type": "gameState", + "moves": "e2e4 c7c5 f2f4 d7d6 g1f3 b8c6 f1c4 g8f6 d2d3 g7g6 e1g1 f8g7", + "wtime": 7598040, + "btime": 8395220, + "winc": 10000, + "binc": 10000, + "status": "started" + } + } + }, + "gameState": { + "value": { + "type": "gameState", + "moves": "e2e4 c7c5 f2f4 d7d6 g1f3 b8c6 f1c4 g8f6 d2d3 g7g6 e1g1 f8g7 b1c3", + "wtime": 7598040, + "btime": 8395220, + "winc": 10000, + "binc": 10000, + "status": "started" + } + }, + "chatLine": { + "value": { + "type": "chatLine", + "username": "thibault", + "text": "Good luck, have fun", + "room": "player" + } + }, + "chatLineSpectator": { + "value": { + "type": "chatLine", + "username": "lovlas", + "text": "!eval", + "room": "spectator" + } + }, + "opponentGoneTrue": { + "value": { + "type": "opponentGone", + "gone": true, + "claimWinInSeconds": 8 + } + }, + "opponentGoneFalse": { + "value": { + "type": "opponentGone", + "gone": false + } + }, + "gameStateResign": { + "value": { + "type": "gameState", + "moves": "e2e4 c7c5 f2f4 d7d6 g1f3 b8c6 f1c4 g8f6 d2d3 g7g6 e1g1 f8g7 b1c3", + "wtime": 7598040, + "btime": 8395220, + "winc": 10000, + "binc": 10000, + "status": "resign", + "winner": "black" + } + } + } + } +}