Nakama Leaderboards and Tournaments API

openapi: 3.0.1
info:
  title: Nakama 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'
externalDocs:
  description: Nakama documentation
  url: https://heroiclabs.com/docs/nakama/
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.
tags:
  - name: Authentication
    description: Authenticate users and issue or refresh session tokens.
  - name: Account
    description: Read, update, and delete the current account and link identities.
  - name: Friends
    description: Manage the friend graph.
  - name: Groups
    description: Create and manage groups (clans) and their members.
  - name: Storage
    description: Read, write, list, and delete storage objects.
  - name: Leaderboards
    description: Write and list leaderboard records.
  - name: Tournaments
    description: List, join, and submit to tournaments.
  - name: Notifications
    description: List and delete in-app notifications.
  - name: RPC
    description: Call custom runtime functions.
paths:
  /v2/account/authenticate/device:
    post:
      operationId: authenticateDevice
      tags:
        - Authentication
      summary: Authenticate a user with a device id against the server.
      security:
        - BasicAuth: []
      parameters:
        - in: query
          name: create
          schema:
            type: boolean
          description: Register the account if the user does not already exist.
        - in: query
          name: username
          schema:
            type: string
          description: Set the username on the account at register. Ignored if the account exists.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthenticateDeviceRequest'
      responses:
        '200':
          description: A session with the current session token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
  /v2/account/authenticate/email:
    post:
      operationId: authenticateEmail
      tags:
        - Authentication
      summary: Authenticate a user with an email and password against the server.
      security:
        - BasicAuth: []
      parameters:
        - in: query
          name: create
          schema:
            type: boolean
        - in: query
          name: username
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthenticateEmailRequest'
      responses:
        '200':
          description: A session with the current session token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
  /v2/account/authenticate/custom:
    post:
      operationId: authenticateCustom
      tags:
        - Authentication
      summary: Authenticate a user with a custom id against the server.
      security:
        - BasicAuth: []
      parameters:
        - in: query
          name: create
          schema:
            type: boolean
        - in: query
          name: username
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthenticateCustomRequest'
      responses:
        '200':
          description: A session with the current session token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
  /v2/account/session/refresh:
    post:
      operationId: sessionRefresh
      tags:
        - Authentication
      summary: Refresh a user's session using a refresh token retrieved from a previous authentication request.
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionRefreshRequest'
      responses:
        '200':
          description: A session with a new session token and refresh token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
  /v2/account:
    get:
      operationId: getAccount
      tags:
        - Account
      summary: Fetch the current user's account.
      responses:
        '200':
          description: The current user's account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
    put:
      operationId: updateAccount
      tags:
        - Account
      summary: Update fields in the current user's account.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAccountRequest'
      responses:
        '200':
          description: The account was updated.
    delete:
      operationId: deleteAccount
      tags:
        - Account
      summary: Delete the current user's account.
      responses:
        '200':
          description: The account was deleted.
  /v2/account/link/device:
    post:
      operationId: linkDevice
      tags:
        - Account
      summary: Add a device id to the social profiles on the current user's account.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountDevice'
      responses:
        '200':
          description: The device was linked.
  /v2/account/unlink/device:
    post:
      operationId: unlinkDevice
      tags:
        - Account
      summary: Remove a device id from the social profiles on the current user's account.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountDevice'
      responses:
        '200':
          description: The device was unlinked.
  /v2/user:
    get:
      operationId: getUsers
      tags:
        - Account
      summary: Fetch zero or more users by id, username, and/or Facebook id.
      parameters:
        - in: query
          name: ids
          schema:
            type: array
            items:
              type: string
          description: The account ids of the users.
        - in: query
          name: usernames
          schema:
            type: array
            items:
              type: string
          description: The account usernames.
        - in: query
          name: facebook_ids
          schema:
            type: array
            items:
              type: string
          description: The Facebook ids of the users.
      responses:
        '200':
          description: A collection of user objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Users'
  /v2/friend:
    get:
      operationId: listFriends
      tags:
        - Friends
      summary: List all friends for the current user.
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
            format: int32
          description: Max number of records to return. Between 1 and 1000.
        - in: query
          name: state
          schema:
            type: integer
            format: int32
          description: 'The friend state to list - 0 friends, 1 invite sent, 2 invite received, 3 blocked.'
        - in: query
          name: cursor
          schema:
            type: string
          description: An optional next page cursor.
      responses:
        '200':
          description: A collection of zero or more friends of the user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FriendList'
    post:
      operationId: addFriends
      tags:
        - Friends
      summary: Add friends by ids or usernames.
      parameters:
        - in: query
          name: ids
          schema:
            type: array
            items:
              type: string
          description: The account ids of the users to add as friends.
        - in: query
          name: usernames
          schema:
            type: array
            items:
              type: string
          description: The usernames of the users to add as friends.
      responses:
        '200':
          description: The friends were added or invited.
    delete:
      operationId: deleteFriends
      tags:
        - Friends
      summary: Delete one or more friends for the current user.
      parameters:
        - in: query
          name: ids
          schema:
            type: array
            items:
              type: string
        - in: query
          name: usernames
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: The friends were deleted.
  /v2/group:
    post:
      operationId: createGroup
      tags:
        - Groups
      summary: Create a new group with the current user as the owner.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateGroupRequest'
      responses:
        '200':
          description: The newly created group.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
  /v2/group/{group_id}/join:
    post:
      operationId: joinGroup
      tags:
        - Groups
      summary: Immediately join an open group, or request to join a closed one.
      parameters:
        - in: path
          name: group_id
          required: true
          schema:
            type: string
          description: The group id to join.
      responses:
        '200':
          description: The user joined or requested to join the group.
  /v2/storage:
    put:
      operationId: writeStorageObjects
      tags:
        - Storage
      summary: Write objects into the storage engine.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WriteStorageObjectsRequest'
      responses:
        '200':
          description: Acknowledgements of the written objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorageObjectAcks'
    post:
      operationId: readStorageObjects
      tags:
        - Storage
      summary: Get objects from the storage engine.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReadStorageObjectsRequest'
      responses:
        '200':
          description: A list of storage objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorageObjects'
  /v2/storage/{collection}:
    get:
      operationId: listStorageObjects
      tags:
        - Storage
      summary: List publicly readable storage objects in a given collection.
      parameters:
        - in: path
          name: collection
          required: true
          schema:
            type: string
          description: The collection to list over.
        - in: query
          name: user_id
          schema:
            type: string
          description: The user id of the storage objects to list. Set empty to list all users.
        - in: query
          name: limit
          schema:
            type: integer
            format: int32
        - in: query
          name: cursor
          schema:
            type: string
      responses:
        '200':
          description: A list of storage objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorageObjectList'
  /v2/storage/delete:
    put:
      operationId: deleteStorageObjects
      tags:
        - Storage
      summary: Delete one or more objects by id or username.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteStorageObjectsRequest'
      responses:
        '200':
          description: The objects were deleted.
  /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'
  /v2/tournament:
    get:
      operationId: listTournaments
      tags:
        - Tournaments
      summary: List current or upcoming tournaments.
      parameters:
        - in: query
          name: category_start
          schema:
            type: integer
            format: int32
        - in: query
          name: category_end
          schema:
            type: integer
            format: int32
        - in: query
          name: limit
          schema:
            type: integer
            format: int32
        - in: query
          name: cursor
          schema:
            type: string
      responses:
        '200':
          description: A list of tournaments.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TournamentList'
  /v2/tournament/{tournament_id}/join:
    post:
      operationId: joinTournament
      tags:
        - Tournaments
      summary: Attempt to join an open and running tournament.
      parameters:
        - in: path
          name: tournament_id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The user joined the tournament.
  /v2/notification:
    get:
      operationId: listNotifications
      tags:
        - Notifications
      summary: Fetch a list of notifications.
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
            format: int32
          description: The number of notifications to get. Between 1 and 100.
        - in: query
          name: cacheable_cursor
          schema:
            type: string
          description: A cursor to page through notifications, usually cached client-side.
      responses:
        '200':
          description: A collection of notifications.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationList'
    delete:
      operationId: deleteNotifications
      tags:
        - Notifications
      summary: Delete one or more notifications for the current user.
      parameters:
        - in: query
          name: ids
          schema:
            type: array
            items:
              type: string
          description: The id of notifications to delete.
      responses:
        '200':
          description: The notifications were deleted.
  /v2/rpc/{id}:
    post:
      operationId: rpcFunc
      tags:
        - RPC
      summary: Execute a Nakama runtime RPC function with a session token.
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The identifier of the runtime function.
        - in: query
          name: http_key
          schema:
            type: string
          description: The runtime http_key for server-to-server calls, in place of a session token.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: string
              description: The payload passed to the function, as a JSON-encoded string.
      responses:
        '200':
          description: The payload returned from the function.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Rpc'
    get:
      operationId: rpcFunc2
      tags:
        - RPC
      summary: Execute a Nakama runtime RPC function with an http key or session token.
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: query
          name: payload
          schema:
            type: string
          description: The payload for the function, as a URL-encoded string.
        - in: query
          name: http_key
          schema:
            type: string
      responses:
        '200':
          description: The payload returned from the function.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Rpc'
components:
  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>`.
  schemas:
    Session:
      type: object
      description: A user's session used to authenticate messages.
      properties:
        created:
          type: boolean
          description: True if the corresponding account was just created, false otherwise.
        token:
          type: string
          description: Authentication credentials (JWT session token).
        refresh_token:
          type: string
          description: Refresh token that can be used to renew a session.
    AuthenticateDeviceRequest:
      type: object
      properties:
        account:
          $ref: '#/components/schemas/AccountDevice'
        create:
          type: boolean
        username:
          type: string
    AuthenticateEmailRequest:
      type: object
      properties:
        account:
          $ref: '#/components/schemas/AccountEmail'
        create:
          type: boolean
        username:
          type: string
    AuthenticateCustomRequest:
      type: object
      properties:
        account:
          $ref: '#/components/schemas/AccountCustom'
        create:
          type: boolean
        username:
          type: string
    SessionRefreshRequest:
      type: object
      properties:
        token:
          type: string
          description: Refresh token.
        vars:
          type: object
          additionalProperties:
            type: string
          description: Extra information passed to the identity providers.
    AccountDevice:
      type: object
      description: Send a device to the server. Used with authenticate/link/unlink and register.
      required:
        - id
      properties:
        id:
          type: string
          description: A device identifier. Must be between 10 and 128 bytes.
        vars:
          type: object
          additionalProperties:
            type: string
          description: Extra information stored on the session.
    AccountEmail:
      type: object
      description: Send an email with password to the server.
      required:
        - email
        - password
      properties:
        email:
          type: string
          description: A valid RFC-5322 email address.
        password:
          type: string
          description: A password, at least 8 characters long.
        vars:
          type: object
          additionalProperties:
            type: string
    AccountCustom:
      type: object
      description: Send a custom id to the server.
      required:
        - id
      properties:
        id:
          type: string
          description: A custom identifier. Must be between 6 and 128 bytes.
        vars:
          type: object
          additionalProperties:
            type: string
    Account:
      type: object
      description: A user's full account, including linked identities and wallet.
      properties:
        user:
          $ref: '#/components/schemas/User'
        wallet:
          type: string
          description: The user's wallet data, as a JSON-encoded string.
        email:
          type: string
        devices:
          type: array
          items:
            $ref: '#/components/schemas/AccountDevice'
        custom_id:
          type: string
        verify_time:
          type: string
          format: date-time
        disable_time:
          type: string
          format: date-time
    UpdateAccountRequest:
      type: object
      properties:
        username:
          type: string
        display_name:
          type: string
        avatar_url:
          type: string
        lang_tag:
          type: string
        location:
          type: string
        timezone:
          type: string
    User:
      type: object
      description: A user in the system.
      properties:
        id:
          type: string
          description: The id of the user's account.
        username:
          type: string
        display_name:
          type: string
        avatar_url:
          type: string
        lang_tag:
          type: string
        location:
          type: string
        timezone:
          type: string
        metadata:
          type: string
          description: Additional information stored as a JSON-encoded string.
        facebook_id:
          type: string
        google_id:
          type: string
        apple_id:
          type: string
        steam_id:
          type: string
        online:
          type: boolean
        edge_count:
          type: integer
          format: int32
          description: Number of related edges to this user (friend count).
        create_time:
          type: string
          format: date-time
        update_time:
          type: string
          format: date-time
    Users:
      type: object
      properties:
        users:
          type: array
          items:
            $ref: '#/components/schemas/User'
    Friend:
      type: object
      description: A friend of a user.
      properties:
        user:
          $ref: '#/components/schemas/User'
        state:
          type: integer
          format: int32
          description: 'The friend status - 0 mutual, 1 invite sent, 2 invite received, 3 blocked.'
        update_time:
          type: string
          format: date-time
    FriendList:
      type: object
      properties:
        friends:
          type: array
          items:
            $ref: '#/components/schemas/Friend'
        cursor:
          type: string
    CreateGroupRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        description:
          type: string
        lang_tag:
          type: string
        avatar_url:
          type: string
        open:
          type: boolean
          description: Whether the group should have open membership.
        max_count:
          type: integer
          format: int32
    Group:
      type: object
      description: A group in the server.
      properties:
        id:
          type: string
        creator_id:
          type: string
        name:
          type: string
        description:
          type: string
        lang_tag:
          type: string
        metadata:
          type: string
        avatar_url:
          type: string
        open:
          type: boolean
        edge_count:
          type: integer
          format: int32
        max_count:
          type: integer
          format: int32
        create_time:
          type: string
          format: date-time
        update_time:
          type: string
          format: date-time
    StorageObject:
      type: object
      description: An object within the storage engine.
      properties:
        collection:
          type: string
          description: The collection which stores the object.
        key:
          type: string
          description: The key of the object within the collection.
        user_id:
          type: string
          description: The user owner of the object.
        value:
          type: string
          description: The value of the object, a JSON-encoded string.
        version:
          type: string
          description: The version hash of the object, for optimistic concurrency.
        permission_read:
          type: integer
          format: int32
          description: '0 no read, 1 owner read, 2 public read.'
        permission_write:
          type: integer
          format: int32
          description: '0 no write, 1 owner write.'
        create_time:
          type: string
          format: date-time
        update_time:
          type: string
          format: date-time
    WriteStorageObject:
      type: object
      required:
        - collection
        - key
        - value
      properties:
        collection:
          type: string
        key:
          type: string
        value:
          type: string
        version:
          type: string
        permission_read:
          type: integer
          format: int32
        permission_write:
          type: integer
          format: int32
    WriteStorageObjectsRequest:
      type: object
      properties:
        objects:
          type: array
          items:
            $ref: '#/components/schemas/WriteStorageObject'
    ReadStorageObjectId:
      type: object
      required:
        - collection
        - key
      properties:
        collection:
          type: string
        key:
          type: string
        user_id:
          type: string
    ReadStorageObjectsRequest:
      type: object
      properties:
        object_ids:
          type: array
          items:
            $ref: '#/components/schemas/ReadStorageObjectId'
    DeleteStorageObjectId:
      type: object
      required:
        - collection
        - key
      properties:
        collection:
          type: string
        key:
          type: string
        version:
          type: string
    DeleteStorageObjectsRequest:
      type: object
      properties:
        object_ids:
          type: array
          items:
            $ref: '#/components/schemas/DeleteStorageObjectId'
    StorageObjects:
      type: object
      properties:
        objects:
          type: array
          items:
            $ref: '#/components/schemas/StorageObject'
    StorageObjectList:
      type: object
      properties:
        objects:
          type: array
          items:
            $ref: '#/components/schemas/StorageObject'
        cursor:
          type: string
    StorageObjectAck:
      type: object
      properties:
        collection:
          type: string
        key:
          type: string
        version:
          type: string
        user_id:
          type: string
    StorageObjectAcks:
      type: object
      properties:
        acks:
          type: array
          items:
            $ref: '#/components/schemas/StorageObjectAck'
    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
    WriteLeaderboardRecordRequest:
      type: object
      properties:
        score:
          type: string
          format: int64
        subscore:
          type: string
          format: int64
        metadata:
          type: string
    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
    Tournament:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        description:
          type: string
        category:
          type: integer
          format: int32
        sort_order:
          type: integer
          format: int32
        size:
          type: integer
          format: int32
        max_size:
          type: integer
          format: int32
        max_num_score:
          type: integer
          format: int32
        can_enter:
          type: boolean
        end_active:
          type: integer
          format: int32
        next_reset:
          type: integer
          format: int32
        duration:
          type: integer
          format: int32
        start_time:
          type: string
          format: date-time
        end_time:
          type: string
          format: date-time
    TournamentList:
      type: object
      properties:
        tournaments:
          type: array
          items:
            $ref: '#/components/schemas/Tournament'
        cursor:
          type: string
    Notification:
      type: object
      description: A notification in the server.
      properties:
        id:
          type: string
        subject:
          type: string
        content:
          type: string
          description: Content payload, a JSON-encoded string.
        code:
          type: integer
          format: int32
          description: 

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