openapi: 3.0.1
info:
  title: Nakama Account Storage 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: Storage
  description: Read, write, list, and delete storage objects.
paths:
  /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.
components:
  schemas:
    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
    DeleteStorageObjectsRequest:
      type: object
      properties:
        object_ids:
          type: array
          items:
            $ref: '#/components/schemas/DeleteStorageObjectId'
    ReadStorageObjectsRequest:
      type: object
      properties:
        object_ids:
          type: array
          items:
            $ref: '#/components/schemas/ReadStorageObjectId'
    ReadStorageObjectId:
      type: object
      required:
      - collection
      - key
      properties:
        collection:
          type: string
        key:
          type: string
        user_id:
          type: string
    StorageObjectAck:
      type: object
      properties:
        collection:
          type: string
        key:
          type: string
        version:
          type: string
        user_id:
          type: string
    DeleteStorageObjectId:
      type: object
      required:
      - collection
      - key
      properties:
        collection:
          type: string
        key:
          type: string
        version:
          type: string
    StorageObjectList:
      type: object
      properties:
        objects:
          type: array
          items:
            $ref: '#/components/schemas/StorageObject'
        cursor:
          type: string
    WriteStorageObjectsRequest:
      type: object
      properties:
        objects:
          type: array
          items:
            $ref: '#/components/schemas/WriteStorageObject'
    StorageObjectAcks:
      type: object
      properties:
        acks:
          type: array
          items:
            $ref: '#/components/schemas/StorageObjectAck'
    StorageObjects:
      type: object
      properties:
        objects:
          type: array
          items:
            $ref: '#/components/schemas/StorageObject'
    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
  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/