adaptorex/doc/api/public/openapi.yaml

Connect all your live interactive storytelling devices and software

openapi: 3.0.2
info:
  title: adaptor:ex RESTful API
  version: 0.0.2
  description: |
    RESTful API for adaptor:ex. Access, create and modify adaptor games.

    Take a look at [this tutorial](https://docs.adaptorex.org/tutorials/server-setup) to find out how to setup an adaptor.ex server.

    On **Security**: You can protect API endpoints with [basic authentication](https://en.wikipedia.org/wiki/Basic_access_authentication). 
    This is by no means the safest authentication procedure but it is all there is for now. 

    We recommend to view it rather as a way of user administration then actual security.

    For basic auth to be effective make sure to only allow https access to your server.

    adaptor:ex provides user roles which are defined in the security `basicAuth` schema. See the [Server Readme]( https://gitlab.com/machina_ex/adaptor_ex/adaptor_ex_server/-/blob/main/README.md?ref_type=heads#secure-with-user-authentication) for details. 

    Endpoints that don't define security roles are open for all users.
  license:
    name: MIT
    url: "https://mit-license.org/"
  contact:
    name: tech@machinaex.de
    url: "https://docs.adaptorex.org"
servers:
  # basic authentication might be enabled
  - url: "{protocol}://{domain}:{port}/api"
    description: Custom server
    variables:
      protocol:
        enum: ["http", "https"]
        default: "http"
      domain:
        default: "localhost"
      port:
        default: "8081"
  - url: "https://server.test.adaptorex.org/api"
    description: Adaptor Development server
tags:
  - name: root
    description: adaptor:ex main features, relevant to all games
  - name: user
    description: organize users and user sessions
  - name: game
    description: interact with a game
  - name: files
    description: >
      manage game media files and directories. 
      List, upload, download, copy, move/rename files and create directories.
  - name: level
    description: get level data, create and modify levels
  - name: state
    description: get levels state data, create and modify states
  - name: schema
    description: get json schema architecture data
  - name: session
    description: get, launch and cancel sessions
  - name: plugin
    description: add and remove plugins and get information about active plugins
  - name: plugin items
    description: add and remove plugins and get information about active plugins
  - name: collection
    description: >
      add and remove data collections and create, update and remove 
      data collection documents.
  - name: items
    description: combined plugin and data collection items endpoint
  - name: history
    description: archive and restore documents and create and restore revisions.
paths:
  /info:
    get:
      tags:
        - root
      summary: get information about the running server instance
      operationId: getInfo
      responses:
        200:
          description: successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                    description: Name of the npm package.
                  version:
                    type: string
                    description: Current installed version of the package.
                  description:
                    type: string
                    description: Short description of the package.
                  homepage:
                    type: string
                    format: uri
                    description: URL to the package's homepage.
                  repository:
                    type: object
                    properties:
                      type:
                        type: string
                        description: Type of repository (e.g., git).
                      url:
                        type: string
                        format: uri
                        description: URL to the repository.
                    required:
                      - type
                      - url
                  license:
                    type: string
                    description: License of the package.
                  latestVersion:
                    type: string
                    description: Latest version available in the npm registry.
                  updateAvailable:
                    type: boolean
                    description: Indicates if an update is available.
        401:
          $ref: "#/components/responses/401Unauthorized"
        403:
          $ref: "#/components/responses/403AccessDenied"
  /config:
    get:
      tags:
        - root
      summary: get adaptor config
      operationId: getConfig
      security:
        - basicAuth: [admin]
      responses:
        200:
          description: successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                    description: url shows plugins where to find the adaptor in the internet
                  host:
                    type: string
                    default: http://localhost
                  port:
                    type: integer
                    default: 8080
                  database:
                    type: object
                    description: database connection setup. NeDB requires files property, MongoDB requires url property.
                    properties:
                      type:
                        type: string
                        enum: ["nedb", "mongodb"]
                      url:
                        type: string
                        default: "mongodb://localhost:27017?replicaSet=adaptor-repl"
                  level:
                    type: string
                    description: current log level
                    enum: [error, warn, info, debug, trace]
                  users:
                    type: array
                    items:
                      $ref: "#/components/schemas/user"
        401:
          $ref: "#/components/responses/401Unauthorized"
        403:
          $ref: "#/components/responses/403AccessDenied"
  /plugins:
    get:
      tags:
        - root
        - plugin
      summary: get available plugins
      description: |
        get a list of all plugins that may be installed by games.
        Contains information about the plugins module package.

        No security rules since not sensitive information and is required by games.
      operationId: getPlugins
      responses:
        200:
          description: successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                    description: name reference for use in adaptor:ex API calls
                  package_name:
                    type: string
                    description: original NPM package name
                  source:
                    type: string
                    enum: ["local", "npm", "internal"]
                    description: source of plugin.
                  installed:
                    type: boolean
                    description: true if plugin is installed
                  title:
                    type: string
                    description: Plugin display title
                  version:
                    type: string
                  description:
                    type: string
                  main:
                    type: string
                    description: entry file
                  path:
                    type: string
                    description: path of directory in server file system (local and internal plugins only)
                  homepage:
                    type: string
                    description: web address of plugin documentation
                  license:
                    type: string
                  dependencies:
                    type: object
                    additionalProperties:
                      type: string
        401:
          $ref: "#/components/responses/401Unauthorized"
        403:
          $ref: "#/components/responses/403AccessDenied"
  /user:
    get:
      tags:
        - root
        - user
      summary: get user list (NOT IMPLEMENTED)
      security:
        - basicAuth: [admin]
      operationId: getUser
      responses:
        200:
          description: successful
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/user"
        401:
          $ref: "#/components/responses/401Unauthorized"
        403:
          $ref: "#/components/responses/403AccessDenied"
    post:
      tags:
        - root
        - user
      summary: create a new user (NOT IMPLEMENTED)
      description: creates a new user that can login to this adaptor editor
      security:
        - basicAuth: [admin]
      operationId: createUser
      requestBody:
        description: user properties
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/user"
      responses:
        201:
          $ref: "#/components/responses/201Created"
        401:
          $ref: "#/components/responses/401Unauthorized"
        403:
          $ref: "#/components/responses/403AccessDenied"
        400:
          $ref: "#/components/responses/400Invalid"
  /me:
    get:
      tags:
        - root
        - user
      summary: get information about the current user
      operationId: getMe
      responses:
        200:
          description: successful
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/user"
        401:
          $ref: "#/components/responses/401Unauthorized"
    put:
      tags:
        - root
        - user
      summary: change my user data (NOT IMPLEMENTED)
      operationId: updateMe
      requestBody:
        description: modified user data
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/user"
      responses:
        200:
          $ref: "#/components/responses/200Update"
        400:
          $ref: "#/components/responses/400Invalid"
        401:
          $ref: "#/components/responses/401Unauthorized"
        404:
          $ref: "#/components/responses/404NotFound"
  /games:
    get:
      tags:
        - root
        - game
      summary: get list of existing games
      operationId: getGames
      responses:
        200:
          description: successful
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/game_preview"
        401:
          $ref: "#/components/responses/401Unauthorized"
  /game:
    post:
      tags:
        - root
        - game
      summary: create a new game
      description: creates a new game and database or loads game from an existing database
      security:
        - basicAuth: [admin]
      operationId: createGame
      requestBody:
        description: game properties
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                template:
                  type: string
                  enum: ["basic", "multiplayer", "openworld"]
      responses:
        201:
          $ref: "#/components/responses/201Created"
        400:
          $ref: "#/components/responses/400Invalid"
        401:
          $ref: "#/components/responses/401Unauthorized"
        403:
          $ref: "#/components/responses/403AccessDenied"
  /game/{game}:
    parameters:
      - $ref: "#/components/parameters/game"
    get:
      tags:
        - game
      summary: get game data overview
      description: preview data describing the game.
      operationId: getGame
      responses:
        200:
          description: successful
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/game"
        401:
          $ref: "#/components/responses/401Unauthorized"
        404:
          $ref: "#/components/responses/404NotFound"
    delete:
      tags:
        - game
      description: delete game with name
      security:
        - basicAuth: [admin, owner]
      operationId: deleteGame
      responses:
        204:
          description: game delete successful
        400:
          $ref: "#/components/responses/400Invalid"
        401:
          $ref: "#/components/responses/401Unauthorized"
        403:
          $ref: "#/components/responses/403AccessDenied"
        404:
          $ref: "#/components/responses/404NotFound"
  /game/{game}/setup:
    parameters:
      - $ref: "#/components/parameters/game"
    post:
      tags:
        - game
      summary: edit game setup
      description: >
        change game setup elements.
      deprecated: true
      security:
        - basicAuth: [admin, owner, developer]
      operationId: editGameSetup
      requestBody:
        description: update values
        content:
          application/json:
            schema:
              type: object
      responses:
        200:
          $ref: "#/components/responses/200Update"
        400:
          $ref: "#/components/responses/400Invalid"
        401:
          $ref: "#/components/responses/401Unauthorized"
        403:
          $ref: "#/components/responses/403AccessDenied"
        404:
          $ref: "#/components/responses/404NotFound"
  /game/{game}/_event:
    parameters:
      - $ref: "#/components/parameters/game"
    post:
      tags:
        - game
      summary: dispatch global game event
      operationId: gameEvent
      requestBody:
        description: event name and payload.
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: event name
                payload:
                  description: the event payload data. Is optional and may be of any type.
      responses:
        200:
          $ref: "#/components/responses/200Executed"
        400:
          $ref: "#/components/responses/400Invalid"
        401:
          $ref: "#/components/responses/401Unauthorized"
        404:
          $ref: "#/components/responses/404NotFound"
  /game/{game}/media:
    parameters:
      - $ref: "#/components/parameters/game"
    get:
      tags:
        - game
      summary: get list of media files
      operationId: getMedia
      deprecated: true
      responses:
        200:
          description: successful
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        400:
          $ref: "#/components/responses/400Invalid"
        401:
          $ref: "#/components/responses/401Unauthorized"
        404:
          $ref: "#/components/responses/404NotFound"
  /game/{game}/files:
    parameters:
      - $ref: "#/components/parameters/game"
    get:
      tags:
        - files
      summary: list files and directories
      description: >
        Returns the contents of the root file directory for this game.
        Use the `path` query parameter to list the contents of a subdirectory.
        Each entry indicates whether it is a file or a directory.
      operationId: listFiles
      parameters:
        - name: path
          in: query
          required: false
          description: >
            Subdirectory path to list. Omit to list the root directory.
            Example: `audio/voice-messages`
          schema:
            type: string
      responses:
        200:
          description: successful
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/file"
        400:
          $ref: "#/components/responses/400Invalid"
        401:
          $ref: "#/components/responses/401Unauthorized"
        404:
          $ref: "#/components/responses/404NotFound"
    post:
      tags:
        - files
      summary: upload one or more files
      description: >
        Upload a file to the game's file storage.
        Use the `path` query parameter to place the file into a subdirectory.
        If the target directory does not exist it will be created automatically.
        Uploading a file with the same name as an existing file will replace it.
      operationId: uploadFiles
      security:
        - basicAuth: [admin, owner, developer, author]
      parameters:
        - name: path
          in: query
          required: false
          description: >
            Target directory path. Omit to upload to the root directory.
            Example: `images/avatars`
          schema:
            type: string
        - name: extract
          in: query
          required: false
          description: >
            Wether to extract .zip archives after upload
            Example: `true`
          schema:
            type: boolean
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - files
              properties:
                files:
                  type: array
                  items:
                    type: string
                    format: binary
                  description: One or more files to upload.
                  minItems: 1
      responses:
        201:
          $ref: "#/components/responses/201UploadDone"
        400:
          $ref: "#/components/responses/400Invalid"
        401:
          $ref: "#/components/responses/401Unauthorized"
        403:
          $ref: "#/components/responses/403AccessDenied"
        404:
          $ref: "#/components/responses/404NotFound"
  /game/{game}/files/{path}:
    parameters:
      - $ref: "#/components/parameters/game"
      - name: path
        in: path
        required: true
        description: >
          Path to the file, including filename or directory.
        example: "images/characters/ada.png"
        schema:
          type: string
    post:
      tags:
        - files
      summary: create a directory
      description: >
        Creates a new directory at the specified path.
        Intermediate parent directories are created automatically if they do not exist.
        Does nothing if the directory already exists.
      operationId: createDirectory
      security:
        - basicAuth: [admin, owner, developer, author]
      responses:
        201:
          $ref: "#/components/responses/201Created"
        400:
          $ref: "#/components/responses/400Invalid"
        401:
          $ref: "#/components/responses/401Unauthorized"
        403:
          $ref: "#/components/responses/403AccessDenied"
    get:
      tags:
        - files
      summary: download a file
      description: Returns the raw file content with the appropriate MIME type.
      operationId: downloadFile
      responses:
        200:
          description: file content
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        401:
          $ref: "#/components/responses/401Unauthorized"
        404:
          $ref: "#/components/responses/404NotFound"
    delete:
      tags:
        - files
      summary: delete a file or directory
      description: Permanently deletes a file or a directory. This action cannot be undone.
      operationId: deleteFile
      security:
        - basicAuth: [admin, owner, developer, author]
      responses:
        204:
          description: file or directory delete successful
        400:
          $ref: "#/components/responses/400Invalid"
        401:
          $ref: "#/components/responses/401Unauthorized"
        403:
          $ref: "#/components/responses/403AccessDenied"
        404:
          $ref: "#/components/responses/404NotFound"
  /game/{game}/files/{path}/_copy:
    parameters:
      - $ref: "#/components/parameters/game"
      - name: path
        in: path
        required: true
        description: >
          Full path to the source file or directory. Example: `images/ada.png`
        schema:
          type: string
    post:
      tags:
        - files
      summary: copy a file
      description: >
        Copies a file or all files in a directory to a new location. The source file is kept unchanged.
        If a file already exists at the destination it will be overwritten.
      operationId: copyFile
      security:
        - basicAuth: [admin, owner, developer, author]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - destination
              properties:
                destination:
                  type: string
                  description: >
                    Target path including the desired filename.
                  example: "images/characters/ada_copy.png"
      responses:
        201:
          $ref: "#/components/responses/201Created"
        400:
          $ref: "#/components/responses/400Invalid"
        401:
          $ref: "#/components/responses/401Unauthorized"
        403:
          $ref: "#/components/responses/403AccessDenied"
        404:
          $ref: "#/components/responses/404NotFound"
  /game/{game}/files/{path}/_move:
    parameters:
      - $ref: "#/components/parameters/game"
      - name: path
        in: path
        required: true
        description: >
          Full path to the source file or directory. Example: `images/ada.png`
        schema:
          type: string
    post:
      tags:
        - files
      summary: move or rename a file or directory
      description: >
        Moves a file or directory to a new path, which also serves as a rename operation
        when the directory part of the path stays the same.
        If a file already exists at the destination it will be overwritten.
      operationId: moveFile
      security:
        - basicAuth: [admin, owner, developer, author]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - destination
              properties:
                destination:
                  type: string
                  description: >
                    Target path including the desired filename if it's a file.
                  example: "images/characters/ada_renamed.png"
      responses:
        200:
          $ref: "#/components/responses/200Update"
        400:
          $ref: "#/components/responses/400Invalid"
        401:
          $ref: "#/components/responses/401Unauthorized"
        403:
          $ref: "#/components/responses/403AccessDenied"
        404:
          $ref: "#/components/responses/404NotFound"
  /game/{game}/files/{path}/_publish:
    parameters:
      - $ref: "#/components/parameters/game"
      - name: path
        in: path
        required: true
        description: >
          Full path to the file or directory. Example: `images/ada.png`
        schema:
          type: string
    post:
      tags:
        - files
      summary: make a file or directory publicly available
      description: >
        Creates a symlink in the public file directory to the specified file or directory.
        If path is a directory all files in that directory will be public even if they are added later.
      operationId: publishFile
      security:
        - basicAuth: [admin, owner, developer, author]
      responses:
        200:
          $ref: "#/components/responses/200Update"
        400:
          $ref: "#/components/responses/400Invalid"
        401:
          $ref: "#/components/responses/401Unauthorized"
        403:
          $ref: "#/components/responses/403AccessDenied"
        404:
          $ref: "#/components/responses/404NotFound"
  /game/{game}/files/{path}/_unpublish:
    parameters:
      - $ref: "#/components/parameters/game"
      - name: path
        in: path
        required: true
        description: >
          Full path to the file or directory. Example: `images/ada.png`
        schema:
          type: string
    post:
      tags:
        - files
      summary: remove a file or directory from the public files directory.
      description: >
        Removes the symlink in the public file directory to the specified file or directory.
        If path is a directory none of the files in that directory will be public anymore.
      operationId: unpublishFile
      security:
        - basicAuth: [admin, owner, developer, author]
      responses:
        200:
          $ref: "#/components/responses/200Update"
        400:
          $ref: "#/components/responses/400Invalid"
        401:
          $ref: "#/components/responses/401Unauthorized"
        403:
          $ref: "#/components/responses/403AccessDenied"
        404:
          $ref: "#/components/responses/404NotFound"
  /game/{game}/level:
    parameters:
      - $ref: "#/components/parameters/game"
    post:
      tags:
        - level
      summary: create new level
      description: If only name (required) is provided, a default level will be created as described in "#/components/schemas/level/default"
      security:
        - basicAuth: [admin, owner, developer, author]
      operationId: createLevel
      requestBody:
        description: level properties
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/level"
      responses:
        201:
          $ref: "#/components/responses/201Created"
        400:
          $ref: "#/components/responses/400Invalid"
        401:
          $ref: "#/components/responses/401Unauthorized"
        403:
          $ref: "#/components/responses/403AccessDenied"
    get:
      tags:
        - level
      summary: find levels by using query parameters
      description: |
        omit parameters to get all the levels or use _sort_by parameter to get a sorted list of levels that match the query

        Use `_archived=true` to get levels that have been archived.
      operationId: findLevel
      parameters:
        - name: name
          in: query
          schema:
            type: string
        - $ref: "#/components/parameters/archived"
        - $ref: "#/components/parameters/sort_by"
        - $ref: "#/components/parameters/sort_direction"
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/skip"
        - $ref: "#/components/parameters/cast_types_false"
        - $ref: "#/components/parameters/params"
      responses:
        200:
          description: level data
          content:
            application/json:
              schema:
                type: array
                items:
                  # sollten hier auch nur die previews zurückgegeben werden?
                  $ref: "#/components/schemas/level"
        401:
          $ref: "#/components/responses/401Unauthorized"
  /game/{game}/level/{level}:
    parameters:
      - $ref: "#/components/parameters/game"
      - $ref: "#/components/parameters/level"
    get:
      tags:
        - level
      summary: get level data
      operationId: getLevel
      parameters:
        - $ref: "#/components/parameters/archived"
      responses:
        200:
          description: successful
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/level"
        400:
          $ref: "#/components/responses/400Invalid"
        401:
          $ref: "#/components/responses/401Unauthorized"
        404:
          $ref: "#/components/responses/404NotFound"
    put:
      tags:
        - level
      summary: update level data
      description: >
        Replace level document. Make sure to include created_at, created_by and created_with properties otherwise they are lost.
        Known Bug: If you use name as identification, updating the name property will lead to missing modification information
      security:
        - basicAuth: [admin, owner, developer, author]
      operationId: updateLevel
      requestBody:
        description: modified level data
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/level"
      responses:
        200:
          $ref: "#/components/responses/200Update"
        400:
          $ref: "#/components/responses/400Invalid"
        401:
          $ref: "#/components/responses/401Unauthorized"
        403:
          $ref: "#/components/responses/403AccessDenied"
        404:
          $ref: "#/components/responses/404NotFound"
    delete:
      tags:
        - level
      summary: permanently delete level
      description: |
        Will delete active levels and levels that have been moved to archive. Deleted levels can not be restored.

        For active levels this will cancel all it's sessions and delete all level revisions.
      security:
        - basicAuth: [admin, owner, developer]
      operationId: deleteLevel
      responses:
        204:
          description: level delete successful
        400:
          $ref: "#/components/responses/400Invalid"
        401:
          $ref: "#/components/responses/401Unauthorized"
        403:
          $ref: "#/components/responses/403AccessDenied"
        404:
          $ref: "#/components/responses/404NotFound"
  /game/{game}/level/{level}/_archive:
    parameters:
      - $ref: "#/components/parameters/game"
      - $ref: "#/components/parameters/level"
    post:
      tags:
        - level
        - history
      summary: move level to archive
      description: |
        Level will be removed from levels collection and moved to levels_archive collection.

        Archive operation will cancel all Sessions for this level and delete all revisions.
      operationId: archiveLevel
      security:
        - basicAuth: [admin, owner, developer, author]
      responses:
        200:
          description: archive level successful
          $ref: "#/components/responses/200Executed"
        400:
          $ref: "#/components/responses/400Invalid"
        401:
          $ref: "#/components/responses/401Unauthorized"
        403:
          $ref: "#/components/responses/403AccessDenied"
        404:
          $ref: "#/components/responses/404NotFound"
  /game/{game}/level/{level}/_restore:
    parameters:
      - $ref: "#/components/parameters/game"
      - $ref: "#/components/parameters/level"
    post:
      tags:
        - level
        - history
      summary: restore archived level
      operationId: restoreLevel
      security:
        - basicAuth: [admin, owner, developer, author]
      responses:
        201:
          description: restore level successful
          $ref: "#/components/responses/201Created"
        400:
          $ref: "#/components/responses/400Invalid"
        401:
          $ref: "#/components/responses/401Unauthorized"
        403:
          $ref: "#/components/responses/403AccessDenied"
        404:
          $ref: "#/components/responses/404NotFound"
  /game/{game}/level/{level}/{operator}:
    post:
      tags:
        - level
      summary: edit level using update operator
      description: >
        Known Bug: If you use name as identification, updating the name property will lead to missing modification information
      security:
        - basicAuth: [admin, owner, developer, author]
      operationId: editLevel
      parameters:
        - $ref: "#/components/parameters/game"
        - $ref: "#/components/parameters/level"
        - $ref: "#/components/parameters/operator"
      requestBody:
        description: update values
        content:
          application/json:
            schema:
              type: object
              example:
                name: newName
                config.arguments.Player.query: "{name:'Testplayer'}"
      responses:
        200:
          $ref: "#/components/responses/200Update"
        400:
          $ref: "#/components/responses/400Invalid"
        401:
          $ref: "#/components/responses/401Unauthorized"
        403:
          $ref: "#/components/responses/403AccessDenied"
        404:
          $ref: "#/components/responses/404NotFound"
  /game/{game}/level/{level}/revision:
    parameters:
      - $ref: "#/components/parameters/game"
      - $ref: "#/components/parameters/level"
    get:
      tags:
        - level
        - history
      summary: get level revisions
      operationId: findLevelRevisions
      description: |
        omit parameters to get all the level revisions or use additional parameters to get a filtered list. Use _sort_by to get a sorted list of level revisions that match the query.
        To get the latest revision of a level, use 

        `/game/{game}/level/{level}/revision/?_sort_by=id&_sort_direction=-1&_limit=1`
      parameters:
        - name: name
          in: query
          schema:
            type: string
        - name: id
          in: query
          schema:
            type: integer
        - $ref: "#/components/parameters/sort_by"
        - $ref: "#/components/parameters/sort_direction"
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/skip"
        - $ref: "#/components/parameters/cast_types_false"
        - $ref: "#/components/parameters/params"
      responses:
        200:
          description: successful
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/level"
        400:
          $ref: "#/components/responses/400Invalid"
        404:
          $ref: "#/components/responses/404NotFound"
    post:
      tags:
        - level
        - history
      summary: create new level revision
      description: Makes a copy of the current level in the level history database. Add name and or description to identify the revision
      operationId: createLevelRevision
      security:
        - basicAuth: [admin, owner, developer, author]
      requestBody:
        description: Revision infos
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: optional name property to identify revision. Response 400 ,"DuplicateError" if name is not unique
                description:
                  type: string
      responses:
        201:
          $ref: "#/components/responses/201Created"
        400:
          $ref: "#/components/responses/400Invalid"
        401:
          $ref: "#/components/responses/401Unauthorized"
        403:
          $ref: "#/components/responses/403AccessDenied"
  /game/{game}/level/{level}/revision/_delete:
    parameters:
      - $ref: "#/components/parameters/game"
      - $ref: "#/components/parameters/level"
    post:
      tags:
        - level
        - history
      summary: batch delete level revisions via query
      description: |
        omit parameters to delete all the level revisions or use additional parameters to delete based on a filtered list. Use _sort_by to get a sorted list of level revisions that match the query.
        To delete all but keep the 10 latest revision of a level, use 

        `/game/{game}/level/{level}/revision/_delete?_sort_by=id&_sort_direction=-1&_skip=10`

        Operation will not fail if no revisions match the query.
      operationId: findAndDeleteLevelRevisions
      security:
        - basicAuth: [admin, owner, developer, author]
      parameters:
        - name: name
          in: query
          schema:
            type: string
        - name: id
          in: query
          schema:
            type: integer
        - $ref: "#/components/parameters/sort_by"
        - $ref: "#/components/parameters/sort_direction"
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/skip"
        - $ref: "#/components/parameters/cast_types_false"
        - $ref: "#/components/parameters/params"
      responses:
        200:
          description: successful
          content:
            application/json:
              schema:
                type: string
                example: "2 revisions deleted for level MyLevel'"
        400:
          $ref: "#/components/responses/400Invalid"
        401:
          $ref: "#/components/responses/401Unauthorized"
        403:
          $ref: "#/components/responses/403AccessDenied"
  /game/{game}/level/{level}/revision/{level_revision}:
    parameters:
      - $ref: "#/components/parameters/game"
      - $ref: "#/components/parameters/level"
      - $ref: "#/components/parameters/level_revision"
    get:
      tags:
        - level
        - history
      summary: get level data of a specific revision
      operationId: getLevel
      responses:
        200:
          description: successful
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/level"
        400:
          $ref: "#/components/responses/400Invalid"
        404:
          $ref: "#/components/responses/404NotFound"
    delete:
      tags:
        - level
        - history
      summary: delete level revision
      operationId: deleteLevelRevision
      security:
        - basicAuth: [admin, owner, developer, author]
      responses:
        204:
          description: level revision delete successful
        400:
          $ref: "#/components/responses/400Invalid"
        401:
          $ref: "#/components/responses/401Unauthorized"
        403:
          $ref: "#/components/responses/403AccessDenied"
        404:
          $ref: "#/components/responses/404NotFound"
  /game/{game}/level/{level}/revision/{level_revision}/_restore:
    parameters:
      - $ref: "#/components/parameters/game"
      - $ref: "#/components/parameters/level"
      - $ref: "#/components/parameters/level_revision"
    post:
      tags:
        - level
        - history
      summary: restore level revision
      description: Overwrite the current level with the level revision
      operationId: restoreLevelRevision
      security:
        - basicAuth: [admin, owner, developer, author]
      responses:
        200:
          description: successful
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/level"
        400:
          $ref: "#/components/responses/400Invalid"
        401:
          $ref: "#/components/responses/401Unauthorized"
        403:
          $ref: "#/components/responses/403AccessDenied"
        404:
          $ref: "#/components/responses/404NotFound"
  /game/{game}/level/{level}/variables:
    parameters:
      - $ref: "#/components/parameters/game"
      - $ref: "#/components/parameters/level"
    get:
      tags:
        - level
      summary: get variables and functions of level context
      operationId: getLevelVariables
      responses:
        200:
          description: successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  level_attributes:
                    type: array
                    example: ["[[name]]", "[[_id]]", "[[custom_attribute]]"]
                    items:
                      type: string
                  level_arguments:
                    type: array
                    example: ["[[Player]]", "[[Player.name]]"]
                    items:
                      type: string
                  plugin_items:
                    type: array
                    example:
                      [
                        "[[devices]]",
                        "[[devices.http]]",
                        "[[devices.http.mydevice.settings]]"
                      ]
                    items:
                      type: string
                  action_data:
                    type: array
                    example:
                      [
                        "[[state]]",
                        "[[state.StateName]]",
                        "[[state.StateName.onEvent]]",
                        "[[state.StateName.onEvent.match]]"
                      ]
                    items:
                      type: string
                  functions:
                    type: array
                    example: ["[[function]]", "[[function.getDate()]]"]
                    items:
                      type: string
        400:
          $ref: "#/components/responses/400Invalid"
        401:
          $ref: "#/components/responses/401Unauthorized"
        404:
          $ref: "#/components/responses/404NotFound"
  /game/{game}/level/{level}/states:
    # might be obsolete since states are in level GET and are pretty useless without actions and contents
    get:
      tags:
        - level
        - state
      summary: get list of level states (This is not implemented because it probably has no use)
      deprecated: true
      parameters:
        - $ref: "#/components/parameters/game"
        - $ref: "#/components/parameters/level"
      responses:
        200:
          description: successful
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/state"
        400:
          $ref: "#/components/responses/400Invalid"
        401:
          $ref: "#/components/responses/401Unauthorized"
        404:
          $ref: "#/components/responses/404NotFound"
  /game/{game}/level/{level}/state:
    post:
      tags:
        - state
        - level
      summary: create new state
      security:
        - basicAuth: [admin, owner, developer, author]
      operationId: createState
      parameters:
        - $ref: "#/components/parameters/game"
        - $ref: "#/components/parameters/level"
      requestBody:
        description: create new states, actions and contents. Use existing state id to replace existing state.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/states"
      responses:
        200:
          $ref: "#/components/responses/200StateUpdate"
        201:
          $ref: "#/components/responses/201StateCreated"
        400:
          $ref: "#/components/responses/400Invalid"
        401:
          $ref: "#/components/responses/401Unauthorized"
        403:
          $ref: "#/components/responses/403AccessDenied"
  /game/{game}/level/{level}/state/{state}:
    parameters:
      - $ref: "#/components/parameters/game"
      - $ref: "#/components/parameters/level"
      - $ref: "#/components/parameters/state"
    get:
      tags:
        - level
        - state
      summary: get state data (not implemented yet)
      responses:
        200:
          description: successful
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/state"
        400:
          $ref: "#/components/responses/400Invalid"
        401:
          $ref: "#/components/responses/401Unauthorized"
        404:
          $ref: "#/components/responses/404NotFound"
    put:
      tags:
        - level
        - state
      summary: replace state data
      security:
        - basicAuth: [admin, owner, developer, author]
      operationId: updateState
      requestBody:
        description: modified state data
        content:
          application/json:
            schema:
              type: object
              description: state properties, action and content elements of a selected state
              properties:
                state:
                  $ref: "#/components/schemas/state"
                actions:
                  type: object
                  additionalProperties:
                    $ref: "#/components/schemas/action"
                contents:
                  type: object
                  additionalProperties:
                    $ref: "#/components/schemas/content"
      responses:
        200:
          $ref: "#/components/responses/200StateUpdate"
        400:
          $ref: "#/components/responses/400Invalid"
        401:
          $ref: "#/components/responses/401Unauthorized"
        403:
          $ref: "#/components/responses/403AccessDenied"
        404:
          $ref: "#/components/responses/404NotFound"
    delete:
      tags:
        - level
        - state
      summary: delete state with id
      security:
        - basicAuth: [admin, owner, developer, author]
      operationId: deleteState
      responses:
        200:
          $ref: "#/components/responses/200StateUpdate"
        400:
          $ref: "#/components/responses/400Invalid"
        401:
          $ref: "#/components/responses/401Unauthorized"
        403:
          $ref: "#/components/responses/403AccessDenied"
        404:
          $ref: "#/components/responses/404NotFound"
  /game/{game}/level_schema:
    get:
      tags:
        - level
        - schema
        - game
      summary: get current game level schema
      description: >
        each level has to validate against this schema. All plugin action and 
        listener schemas are merged inside. It may change and you can subscribe 
        to changes. See ./asyncapi.yaml.
      operationId: getLevelSchema
      parameters:
        - $ref: "#/components/parameters/game"
      responses:
        200:
          description: successful. Response content-length might well be > 50000
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/meta_schema"
        400:
          $ref: "#/components/responses/400Invalid"
        401:
          $ref: "#/components/responses/401Unauthorized"
        404:
          $ref: "#/components/responses/404NotFound"
  /game/{game}/actions:
    parameters:
      - $ref: "#/components/parameters/game"
    get:
      tags:
        - schema
        - game
      summary: get schemas of all actions currently available
      description: >
        Omit query parameters to get all actions available. 
        Use query parameters to get a single action or all actions of a plugin.
      operationId: getActions
      parameters:
        - name: action
          in: query
          schema:
            type: string
        - name: plugin
          in: query
          schema:
            type: string
        - $ref: "#/components/parameters/sort_by"
        - $ref: "#/components/parameters/sort_direction"
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/skip"
        - $ref: "#/components/parameters/cast_types_false"
        - $ref: "#/components/parameters/params"
      responses:
        200:
          description: successful
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/action_schema"
        400:
          $ref: "#/components/responses/400Invalid"
        401:
          $ref: "#/components/responses/401Unauthorized"
        404:
          $ref: "#/components/responses/404NotFound"
  /game/{game}/session:
    parameters:
      - $ref: "#/components/parameters/game"
    post:
      tags:
        - session
      summary: launch new session
      operationId: launchSession
      security:
        - basicAuth: [admin, owner, developer, author, operator]
      requestBody:
        description: session properties
        content:
          application/json:
            schema:
              type: object
              required: ["level"]
              properties:
                name:
                  type: string
                  description: optional name property to identify session
                level:
                  type: string
                  description: level name or _id the session is based on
                arguments:
                  $ref: "#/components/schemas/arguments"
      responses:
        201:
          $ref: "#/components/responses/201Created"
        400:
          $ref: "#/components/responses/400Invalid"
        401:
          $ref: "#/components/responses/401Unauthorized"
        403:
          $ref: "#/components/responses/403AccessDenied"
        404:
          $ref: "#/components/responses/404NotFound"
    get:
      tags:
        - session
      summary: find sessions by using query parameters
      description: |
        omit parameters to get all active sessions or use _sort_by parameter to get 
        a sorted list of sessions that match the query

        Use `_archived=true` to get sessions that have been canceled.
      operationId: findSessions
      parameters:
        - name: name
          in: query
          schema:
            type: string
        - name: level
          description: level _id
          in: query
          schema:
            type: string
        - name: level_name
          description: level name property
          in: query
          schema:
            type: string
        - $ref: "#/components/parameters/archived"
        - $ref: "#/components/parameters/sort_by"
        - $ref: "#/components/parameters/sort_direction"
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/skip"
        - $ref: "#/components/parameters/cast_types_false"
        - $ref: "#/compone