Lichess Tournaments (Swiss) API

openapi: 3.1.0
info:
  version: 2.0.144
  title: Lichess.org API reference Account Tournaments (Swiss) API
  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

    Welcome to the reference for the Lichess API! Lichess is free/libre,

    open-source chess server powered by volunteers and donations.

    - Get help in the [Lichess Discord channel](https://discord.gg/lichess)

    - API demo app with OAuth2 login and gameplay: [source](https://github.com/lichess-org/api-demo) / [demo](https://lichess-org.github.io/api-demo/)

    - API UI app with OAuth2 login and endpoint forms: [source](https://github.com/lichess-org/api-ui) / [website](https://lichess.org/api/ui)

    - [Contribute to this documentation on Github](https://github.com/lichess-org/api)

    - Check out [Lichess widgets to embed in your website](https://lichess.org/developers)

    - [Download all Lichess rated games](https://database.lichess.org/)

    - [Download all Lichess puzzles with themes, ratings and votes](https://database.lichess.org/#puzzles)

    - [Download all evaluated positions](https://database.lichess.org/#evals)


    ## Endpoint

    All requests go to `https://lichess.org` (unless otherwise specified).


    ## Clients

    - [Python general API](https://github.com/lichess-org/berserk)

    - [MicroPython general API](https://github.com/mkomon/uberserk)

    - [Python general API - async](https://pypi.org/project/async-lichess-sdk)

    - [Python Lichess Bot](https://github.com/lichess-bot-devs/lichess-bot)

    - [Python Board API for Certabo](https://github.com/haklein/certabo-lichess)

    - [Java general API](https://github.com/tors42/chariot)

    - [JavaScript & TypeScript general API](https://github.com/devjiwonchoi/equine)

    - [LichessNET - C# API Wrapper](https://github.com/Rabergsel/LichessNET)

    - [.NET general API](https://github.com/Dblike/LichessSharp)


    ## Rate limiting

    All requests are rate limited using various strategies,

    to ensure the API remains responsive for everyone.

    Only make one request at a time.

    If you receive an HTTP response with a [429 status](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#429),

    you have exceded one of the rate limits.

    In most cases, waiting one minute before retrying will be sufficient, but some limits may require longer.

    Reduce your request frequency before retrying.


    ## Streaming with ND-JSON

    Some API endpoints stream their responses as [Newline Delimited JSON a.k.a. **nd-json**](https://github.com/ndjson/ndjson-spec), with one JSON object per line.


    Here''s a [JavaScript utility function](https://gist.github.com/ornicar/a097406810939cf7be1df8ea30e94f3e) to help reading NDJSON streamed responses.


    ## Authentication

    ### Which authentication method is right for me?

    [Read about the Lichess API authentication methods and code examples](https://github.com/lichess-org/api/blob/master/example/README.md)


    ### Personal Access Token

    Personal API access tokens allow you to quickly interact with Lichess API without going through an OAuth flow.

    - [Generate a personal access token](https://lichess.org/account/oauth/token)

    - `curl https://lichess.org/api/account -H "Authorization: Bearer {token}"`

    - [NodeJS example](https://github.com/lichess-org/api/tree/master/example/oauth-personal-token)


    ### Token Security

    - Keep your tokens secret. Do not share them in public repositories or public forums.

    - Your tokens can be used to make your account perform arbitrary actions (within the limits of the tokens'' scope). You remain responsible for all activities on your account.

    - Do not hardcode tokens in your application''s code. Use environment variables or a secure storage and ensure they are not shipped/exposed to users. Be especially careful that they are not included in frontend bundles or apps that are shipped to users.

    - If you suspect a token has been compromised, revoke it immediately.


    To see your active tokens or revoke them, see [your Personal API access tokens](https://lichess.org/account/oauth/token).


    ### Authorization Code Flow with PKCE

    The authorization code flow with PKCE allows your users to **login with Lichess**.

    Lichess supports unregistered and public clients (no client authentication, choose any unique client id).

    The only accepted code challenge method is `S256`.

    Access tokens are long-lived (expect one year), unless they are revoked.

    Refresh tokens are not supported.


    See the [documentation for the OAuth endpoints](#tag/OAuth) or

    the [PKCE RFC](https://datatracker.ietf.org/doc/html/rfc7636#section-4) for a precise protocol description.


    - [Demo app](https://lichess-org.github.io/api-demo/)

    - [Minimal client-side example](https://github.com/lichess-org/api/tree/master/example/oauth-app)

    - [Flask/Python example](https://github.com/lakinwecker/lichess-oauth-flask)

    - [Java example](https://github.com/tors42/lichess-oauth-pkce-app)

    - [NodeJS Passport strategy to login with Lichess OAuth2](https://www.npmjs.com/package/passport-lichess)


    #### Real life examples

    - [PyChess](https://github.com/gbtami/pychess-variants) ([source code](https://github.com/gbtami/pychess-variants))

    - [Lichess4545](https://www.lichess4545.com/) ([source code](https://github.com/cyanfish/heltour))

    - [English Chess Federation](https://ecf.octoknight.com/)

    - [Rotherham Online Chess](https://rotherhamonlinechess.azurewebsites.net/tournaments)


    ### Token format

    Access tokens and authorization codes match `^[A-Za-z0-9_]+$`.

    The length of tokens can be increased without notice. Make sure your application can handle at least 512 characters.

    By convention tokens have a recognizable prefix, but do not rely on this.

    '
servers:
- url: https://lichess.org
- url: https://lichess.dev
- url: http://localhost:{port}
  variables:
    port:
      default: '8080'
- url: http://l.org
tags:
- name: Tournaments (Swiss)
  description: 'Access Swiss tournaments played on Lichess.

    [Read more about Swiss tournaments.](https://lichess.org/swiss).

    '
paths:
  /api/swiss/new/{teamId}:
    post:
      operationId: apiSwissNew
      summary: Create a new Swiss tournament
      description: "Create a Swiss tournament for your team.\nThis endpoint mirrors the Swiss tournament form from your team pagee.\nYou can create up to 12 tournaments per day.\nAdditional restrictions:\n  - clock.limit + clock.increment > 0\n  - 15s and 0+1 variant tournaments cannot be rated\n"
      tags:
      - Tournaments (Swiss)
      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: integer
                  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
                  format: int64
                  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.

                    Set to 99999999 to manually schedule each round from the tournament UI.

                    If empty or -1, a sensible value is picked automatically.

                    '
                  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/SwissFromPositionFEN'
                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.

                    Two usernames per line, separated by a space.

                    '
                manualPairings:
                  type: string
                  description: 'Manual pairings for the next round.

                    Two usernames per line, separated by a space. Example:

                    ```

                    PlayerA PlayerB

                    PlayerC PlayerD

                    ```

                    To give a bye (1 point) to a player instead of a pairing, add a line like so:

                    ```

                    PlayerE 1

                    ```

                    Missing players will be considered absent and get zero points.

                    '
                chatFor:
                  type: integer
                  description: 'Who can read and write in the chat.

                    - 0  = No-one

                    - 10 = Only team leaders

                    - 20 = Only team members

                    - 30 = All Lichess players

                    '
                  default: 20
                  enum:
                  - 0
                  - 10
                  - 20
                  - 30
                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.playYourGames:
                  type: boolean
                  description: 'Only let players join if they have played their last swiss game.

                    If they failed to show up in a recent swiss event, they won''t be able to enter yours.

                    This results in a better swiss experience for the players who actually show up.

                    '
                  default: false
                conditions.allowList:
                  type: string
                  description: 'Predefined list of usernames that are allowed to join, separated by commas.

                    If this list is non-empty, then usernames absent from this list will be forbidden to join.

                    Adding `%titled` to the list additionally allows any titled player to join.

                    Example: `thibault,german11,%titled`

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

        '
      tags:
      - Tournaments (Swiss)
      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.\nBe mindful not to make important changes to ongoing tournaments.\nAdditional restrictions:\n  - clock.limit + clock.increment > 0\n  - 15s and 0+1 variant tournaments cannot be rated\n"
      tags:
      - Tournaments (Swiss)
      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: integer
                  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
                  format: int64
                  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.

                    Set to 99999999 to manually schedule each round from the tournament UI, or [with the API](#tag/tournaments-swiss/POST/api/swiss/{id}/schedule-next-round).

                    If empty or -1, a sensible value is picked automatically.

                    '
                  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/SwissFromPositionFEN'
                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.

                    Two usernames per line, separated by a space.

                    '
                manualPairings:
                  type: string
                  description: 'Manual pairings for the next round.

                    Two usernames per line, separated by a space.

                    Present players without a valid pairing will be given a bye, which is worth 1 point.

                    Forfeited players will get 0 points.

                    '
                chatFor:
                  type: integer
                  description: 'Who can read and write in the chat.

                    - 0  = No-one

                    - 10 = Only team leaders

                    - 20 = Only team members

                    - 30 = All Lichess players

                    '
                  default: 20
                  enum:
                  - 0
                  - 10
                  - 20
                  - 30
                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.playYourGames:
                  type: boolean
                  description: 'Only let players join if they have played their last swiss game.

                    If they failed to show up in a recent swiss event, they won''t be able to enter yours.

                    This results in a better swiss experience for the players who actually show up.

                    '
                  default: false
                conditions.allowList:
                  type: string
                  description: 'Predefined list of usernames that are allowed to join, separated by commas.

                    If this list is non-empty, then usernames absent from this list will be forbidden to join.

                    Adding `%titled` to the list additionally allows any titled player to join.

                    Example: `thibault,german11,%titled`

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

        This sets the `roundInterval` field to `99999999`, i.e. manual scheduling.

        All further rounds will need to be manually scheduled, unless the `roundInterval` field is changed back to automatic scheduling.

        '
      tags:
      - Tournaments (Swiss)
      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
                  format: int64
                  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.

        '
      tags:
      - Tournaments (Swiss)
      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
        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.

        It''s possible to join again later. Points are preserved.

        '
      tags:
      - Tournaments (Swiss)
      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

        '
      tags:
      - Tournaments (Swiss)
      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.

        Documentation: <https://www.fide.com/FIDE/handbook/C04Annex2_TRF16.pdf>

        Example: <https://lichess.org/swiss/j8rtJ5GL.trf>

        '
      tags:
      - Tournaments (Swiss)
      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](#description/streaming-with-nd-json) format.\nGames are sorted by chronological order.\nThe game stream is throttled, depending on who is making the request:\n  - Anonymous request: 20 games per second\n  - [OAuth2 authenticated](#description/authentication) request: 30 games per second\n"
      tags:
      - Tournaments (Swiss)
      security: []
      parameters:
      - $ref: '#/components/parameters/AcceptPgnOrNdjson'
      - 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.

          Either as PGN comments: `2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] }`

          Or in a `clocks` JSON field, as centisecond integers, depending on the response type.

          '
        schema:
          type: boolean
          default: false
      - in: query
        name: evals
        description: 'Include analysis evaluations and comments, when available.

          Either as PGN comments: `12. Bxf6 { [%eval 0.23] } a3 { [%eval -1.09] }`

          Or in an `analysis` JSON field, depending on the response type.

          '
        schema:
          type: boolean
          default: false
      - in: query
        name: accuracy
        description: 'Include [accuracy percent](https://lichess.org/page/accuracy) of each player, when available. Only available in JS

# --- truncated at 32 KB (50 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lichess/refs/heads/main/openapi/lichess-tournaments-swiss-api-openapi.yml