Lichess API — Users

naftiko: 1.0.0-alpha2
info:
  label: Lichess API — Users
  description: 'Lichess API — Users. 13 operations. Lead operation: Get real-time users status. Self-contained Naftiko capability covering one Lichess business surface.'
  tags:
  - Lichess
  - Users
  created: '2026-05-25'
  modified: '2026-05-25'
binds:
- namespace: env
  keys:
    LICHESS_API_TOKEN: LICHESS_API_TOKEN
capability:
  consumes:
  - type: http
    namespace: users
    baseUri: https://lichess.org
    description: Lichess Users business capability. Self-contained, no shared references.
    resources:
    - name: users-status
      path: /api/users/status
      operations:
      - name: apiusersstatus
        method: GET
        description: 'Get real-time users status'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: ids
          in: query
          type: string
          required: false
        - name: withSignal
          in: query
          type: string
          required: false
        - name: withGameIds
          in: query
          type: string
          required: false
        - name: withGameMetas
          in: query
          type: string
          required: false
    - name: player
      path: /api/player
      operations:
      - name: player
        method: GET
        description: 'Get all top 10'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: player-top-nb-perftype
      path: /api/player/top/{nb}/{perfType}
      operations:
      - name: playertopnbperftype
        method: GET
        description: 'Get one leaderboard'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: nb
          in: path
          type: string
          required: true
        - name: perfType
          in: path
          type: string
          required: true
    - name: user-username
      path: /api/user/{username}
      operations:
      - name: apiuser
        method: GET
        description: 'Get user public data'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: username
          in: path
          type: string
          required: true
        - name: trophies
          in: query
          type: string
          required: false
        - name: profile
          in: query
          type: string
          required: false
        - name: rank
          in: query
          type: string
          required: false
        - name: fideId
          in: query
          type: string
          required: false
    - name: user-username-rating-history
      path: /api/user/{username}/rating-history
      operations:
      - name: apiuserratinghistory
        method: GET
        description: 'Get rating history of a user'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: username
          in: path
          type: string
          required: true
    - name: user-username-perf-perf
      path: /api/user/{username}/perf/{perf}
      operations:
      - name: apiuserperf
        method: GET
        description: 'Get performance statistics of a user'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: username
          in: path
          type: string
          required: true
        - name: perf
          in: path
          type: string
          required: true
    - name: user-username-activity
      path: /api/user/{username}/activity
      operations:
      - name: apiuseractivity
        method: GET
        description: 'Get user activity'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: username
          in: path
          type: string
          required: true
    - name: users
      path: /api/users
      operations:
      - name: apiusers
        method: POST
        description: 'Get users by ID'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: profile
          in: query
          type: string
          required: false
        - name: rank
          in: query
          type: string
          required: false
        - name: body
          in: body
          type: object
          required: false
    - name: streamer-live
      path: /api/streamer/live
      operations:
      - name: streamerlive
        method: GET
        description: 'Get live streamers'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: crosstable-user1-user2
      path: /api/crosstable/{user1}/{user2}
      operations:
      - name: apicrosstable
        method: GET
        description: 'Get crosstable'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: user1
          in: path
          type: string
          required: true
        - name: user2
          in: path
          type: string
          required: true
        - name: matchup
          in: query
          type: string
          required: false
    - name: player-autocomplete
      path: /api/player/autocomplete
      operations:
      - name: apiplayerautocomplete
        method: GET
        description: 'Autocomplete usernames'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: term
          in: query
          type: string
          required: false
        - name: exists
          in: query
          type: string
          required: false
        - name: object
          in: query
          type: string
          required: false
        - name: names
          in: query
          type: string
          required: false
        - name: friend
          in: query
          type: string
          required: false
        - name: team
          in: query
          type: string
          required: false
        - name: tour
          in: query
          type: string
          required: false
        - name: swiss
          in: query
          type: string
          required: false
        - name: teacher
          in: query
          type: string
          required: false
    - name: user-username-note
      path: /api/user/{username}/note
      operations:
      - name: writenote
        method: POST
        description: 'Add a note for a user'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: username
          in: path
          type: string
          required: true
        - name: body
          in: body
          type: object
          required: false
      - name: readnote
        method: GET
        description: 'Get notes for a user'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: username
          in: path
          type: string
          required: true
    authentication:
      type: bearer
      value: '{{env.LICHESS_API_TOKEN}}'
      placement: header
  exposes:
  - type: rest
    namespace: users-rest
    port: 8080
    description: REST adapter for Lichess Users. One Spectral-compliant resource per consumed operation.
    resources:
    - path: /v1/api/users/status
      name: users-status
      description: REST surface for users-status.
      operations:
      - method: GET
        name: apiusersstatus
        description: 'Get real-time users status'
        call: users.apiusersstatus
        with:
          ids: rest.query.ids
          withSignal: rest.query.withSignal
          withGameIds: rest.query.withGameIds
          withGameMetas: rest.query.withGameMetas
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/player
      name: player
      description: REST surface for player.
      operations:
      - method: GET
        name: player
        description: 'Get all top 10'
        call: users.player
        with:
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/player/top/{nb}/{perfType}
      name: player-top-nb-perftype
      description: REST surface for player-top-nb-perftype.
      operations:
      - method: GET
        name: playertopnbperftype
        description: 'Get one leaderboard'
        call: users.playertopnbperftype
        with:
          nb: rest.path.nb
          perfType: rest.path.perfType
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/user/{username}
      name: user-username
      description: REST surface for user-username.
      operations:
      - method: GET
        name: apiuser
        description: 'Get user public data'
        call: users.apiuser
        with:
          username: rest.path.username
          trophies: rest.query.trophies
          profile: rest.query.profile
          rank: rest.query.rank
          fideId: rest.query.fideId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/user/{username}/rating-history
      name: user-username-rating-history
      description: REST surface for user-username-rating-history.
      operations:
      - method: GET
        name: apiuserratinghistory
        description: 'Get rating history of a user'
        call: users.apiuserratinghistory
        with:
          username: rest.path.username
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/user/{username}/perf/{perf}
      name: user-username-perf-perf
      description: REST surface for user-username-perf-perf.
      operations:
      - method: GET
        name: apiuserperf
        description: 'Get performance statistics of a user'
        call: users.apiuserperf
        with:
          username: rest.path.username
          perf: rest.path.perf
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/user/{username}/activity
      name: user-username-activity
      description: REST surface for user-username-activity.
      operations:
      - method: GET
        name: apiuseractivity
        description: 'Get user activity'
        call: users.apiuseractivity
        with:
          username: rest.path.username
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/users
      name: users
      description: REST surface for users.
      operations:
      - method: POST
        name: apiusers
        description: 'Get users by ID'
        call: users.apiusers
        with:
          profile: rest.query.profile
          rank: rest.query.rank
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/streamer/live
      name: streamer-live
      description: REST surface for streamer-live.
      operations:
      - method: GET
        name: streamerlive
        description: 'Get live streamers'
        call: users.streamerlive
        with:
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/crosstable/{user1}/{user2}
      name: crosstable-user1-user2
      description: REST surface for crosstable-user1-user2.
      operations:
      - method: GET
        name: apicrosstable
        description: 'Get crosstable'
        call: users.apicrosstable
        with:
          user1: rest.path.user1
          user2: rest.path.user2
          matchup: rest.query.matchup
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/player/autocomplete
      name: player-autocomplete
      description: REST surface for player-autocomplete.
      operations:
      - method: GET
        name: apiplayerautocomplete
        description: 'Autocomplete usernames'
        call: users.apiplayerautocomplete
        with:
          term: rest.query.term
          exists: rest.query.exists
          object: rest.query.object
          names: rest.query.names
          friend: rest.query.friend
          team: rest.query.team
          tour: rest.query.tour
          swiss: rest.query.swiss
          teacher: rest.query.teacher
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/user/{username}/note
      name: user-username-note
      description: REST surface for user-username-note.
      operations:
      - method: POST
        name: writenote
        description: 'Add a note for a user'
        call: users.writenote
        with:
          username: rest.path.username
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
      - method: GET
        name: readnote
        description: 'Get notes for a user'
        call: users.readnote
        with:
          username: rest.path.username
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: users-mcp
    port: 9090
    transport: http
    description: MCP adapter for Lichess Users. One tool per consumed operation.
    tools:
    - name: lichess-apiusersstatus
      description: 'Get real-time users status'
      hints:
        readOnly: true
        destructive: false
        idempotent: false
      call: users.apiusersstatus
      with:
        ids: tools.ids
        withSignal: tools.withSignal
        withGameIds: tools.withGameIds
        withGameMetas: tools.withGameMetas
      outputParameters:
      - type: object
        mapping: $.
    - name: lichess-player
      description: 'Get all top 10'
      hints:
        readOnly: true
        destructive: false
        idempotent: false
      call: users.player
      with:
      outputParameters:
      - type: object
        mapping: $.
    - name: lichess-playertopnbperftype
      description: 'Get one leaderboard'
      hints:
        readOnly: true
        destructive: false
        idempotent: false
      call: users.playertopnbperftype
      with:
        nb: tools.nb
        perfType: tools.perfType
      outputParameters:
      - type: object
        mapping: $.
    - name: lichess-apiuser
      description: 'Get user public data'
      hints:
        readOnly: true
        destructive: false
        idempotent: false
      call: users.apiuser
      with:
        username: tools.username
        trophies: tools.trophies
        profile: tools.profile
        rank: tools.rank
        fideId: tools.fideId
      outputParameters:
      - type: object
        mapping: $.
    - name: lichess-apiuserratinghistory
      description: 'Get rating history of a user'
      hints:
        readOnly: true
        destructive: false
        idempotent: false
      call: users.apiuserratinghistory
      with:
        username: tools.username
      outputParameters:
      - type: object
        mapping: $.
    - name: lichess-apiuserperf
      description: 'Get performance statistics of a user'
      hints:
        readOnly: true
        destructive: false
        idempotent: false
      call: users.apiuserperf
      with:
        username: tools.username
        perf: tools.perf
      outputParameters:
      - type: object
        mapping: $.
    - name: lichess-apiuseractivity
      description: 'Get user activity'
      hints:
        readOnly: true
        destructive: false
        idempotent: false
      call: users.apiuseractivity
      with:
        username: tools.username
      outputParameters:
      - type: object
        mapping: $.
    - name: lichess-apiusers
      description: 'Get users by ID'
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: users.apiusers
      with:
        profile: tools.profile
        rank: tools.rank
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: lichess-streamerlive
      description: 'Get live streamers'
      hints:
        readOnly: true
        destructive: false
        idempotent: false
      call: users.streamerlive
      with:
      outputParameters:
      - type: object
        mapping: $.
    - name: lichess-apicrosstable
      description: 'Get crosstable'
      hints:
        readOnly: true
        destructive: false
        idempotent: false
      call: users.apicrosstable
      with:
        user1: tools.user1
        user2: tools.user2
        matchup: tools.matchup
      outputParameters:
      - type: object
        mapping: $.
    - name: lichess-apiplayerautocomplete
      description: 'Autocomplete usernames'
      hints:
        readOnly: true
        destructive: false
        idempotent: false
      call: users.apiplayerautocomplete
      with:
        term: tools.term
        exists: tools.exists
        object: tools.object
        names: tools.names
        friend: tools.friend
        team: tools.team
        tour: tools.tour
        swiss: tools.swiss
        teacher: tools.teacher
      outputParameters:
      - type: object
        mapping: $.
    - name: lichess-writenote
      description: 'Add a note for a user'
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: users.writenote
      with:
        username: tools.username
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: lichess-readnote
      description: 'Get notes for a user'
      hints:
        readOnly: true
        destructive: false
        idempotent: false
      call: users.readnote
      with:
        username: tools.username
      outputParameters:
      - type: object
        mapping: $.