openapi: 3.0.1
info:
  title: Nakama Account Leaderboards API
  description: 'Representative OpenAPI description of the core REST API for Nakama, the open-source game and app backend server by Heroic Labs. Nakama''s public HTTP API is generated by the gRPC-gateway from `api/api.proto` and is published upstream as `apigrpc/apigrpc.swagger.json` in the heroiclabs/nakama repository. This document reconstructs the primary client-facing surface: authentication, accounts and identity linking, social (friends and groups), storage, leaderboards and tournaments, notifications, and custom RPCs.


    Authentication endpoints are guarded by the server key using HTTP Basic auth, where the server key is the username and the password is empty. All other endpoints are authorized with the JWT session token returned by an authenticate call, sent as `Authorization: Bearer <session_token>`. RPC endpoints may alternatively be called server-to-server with an `http_key` query parameter.'
  termsOfService: https://heroiclabs.com/terms/
  contact:
    name: Heroic Labs
    url: https://heroiclabs.com/
    email: support@heroiclabs.com
  license:
    name: Apache 2.0
    url: https://github.com/heroiclabs/nakama/blob/master/LICENSE
  version: '2.0'
servers:
- url: http://127.0.0.1:7350
  description: Default self-hosted Nakama server. Replace host/port with your Heroic Cloud project URL in production.
security:
- BearerAuth: []
tags:
- name: Leaderboards
  description: Write and list leaderboard records.
paths:
  /v2/leaderboard/{leaderboard_id}:
    get:
      operationId: listLeaderboardRecords
      tags:
      - Leaderboards
      summary: List records from a leaderboard.
      parameters:
      - in: path
        name: leaderboard_id
        required: true
        schema:
          type: string
        description: The leaderboard id.
      - in: query
        name: owner_ids
        schema:
          type: array
          items:
            type: string
        description: One or more owners to retrieve records for.
      - in: query
        name: limit
        schema:
          type: integer
          format: int32
      - in: query
        name: cursor
        schema:
          type: string
      responses:
        '200':
          description: A list of leaderboard records.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeaderboardRecordList'
    post:
      operationId: writeLeaderboardRecord
      tags:
      - Leaderboards
      summary: Write a record to a leaderboard.
      parameters:
      - in: path
        name: leaderboard_id
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WriteLeaderboardRecordRequest'
      responses:
        '200':
          description: The written leaderboard record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeaderboardRecord'
components:
  schemas:
    WriteLeaderboardRecordRequest:
      type: object
      properties:
        score:
          type: string
          format: int64
        subscore:
          type: string
          format: int64
        metadata:
          type: string
    LeaderboardRecord:
      type: object
      description: Represents a complete leaderboard record with all scores and associated metadata.
      properties:
        leaderboard_id:
          type: string
        owner_id:
          type: string
        username:
          type: string
        score:
          type: string
          format: int64
        subscore:
          type: string
          format: int64
        num_score:
          type: integer
          format: int32
        metadata:
          type: string
        create_time:
          type: string
          format: date-time
        update_time:
          type: string
          format: date-time
        expiry_time:
          type: string
          format: date-time
        rank:
          type: string
          format: int64
    LeaderboardRecordList:
      type: object
      properties:
        records:
          type: array
          items:
            $ref: '#/components/schemas/LeaderboardRecord'
        owner_records:
          type: array
          items:
            $ref: '#/components/schemas/LeaderboardRecord'
        next_cursor:
          type: string
        prev_cursor:
          type: string
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: HTTP Basic auth using the server key as the username and an empty password. Guards the authenticate endpoints.
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'The JWT session token returned by an authenticate call, sent as `Authorization: Bearer <session_token>`.'
externalDocs:
  description: Nakama documentation
  url: https://heroiclabs.com/docs/nakama/