neko-rooms/OpenApi.yml

openapi: 3.0.0
info:
  title: Neko Rooms
  version: 1.0.0
servers:
  # Added by API Auto Mocking Plugin
  - description: SwaggerHub API Auto Mocking
    url: https://virtserver.swaggerhub.com/m1k1o/neko-rooms/1.0.0
tags:
  - name: config
    description: config endpoints
  - name: rooms
    description: room endpoints
paths:
  /api/config/rooms:
    get:
      tags:
        - config
      summary: Get rooms config
      operationId: roomsConfig
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoomsConfig'
        '500':
          description: Internal server error
  /api/rooms:
    get:
      tags:
        - rooms
      summary: List all rooms
      operationId: roomsList
      parameters:
        - in: query
          name: labels
          schema:
            type: object
            additionalProperties: 
              type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RoomEntry'
        '500':
          description: Internal server error
    post:
      tags:
        - rooms
      summary: Create new room
      operationId: roomCreate
      parameters:
        - in: query
          name: start
          required: false
          schema:
            type: boolean
            default: true
            description: Start room after creation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RoomSettings'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoomEntry'
        '400':
          description: Bad request
        '500':
          description: Internal server error
  /api/rooms/{roomId}:
    get:
      tags:
        - rooms
      summary: Get room entry
      operationId: roomGet
      parameters:
        - in: path
          name: roomId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoomEntry'
        '400':
          description: Bad request
        '404':
          description: Room not found
        '500':
          description: Internal server error
    delete:
      tags:
        - rooms
      summary: Remove room
      operationId: roomRemove
      parameters:
        - in: path
          name: roomId
          required: true
          schema:
            type: string
      responses:
        '204':
          description: OK
        '404':
          description: Room not found
        '500':
          description: Internal server error
  /api/rooms/{roomName}/by-name:
    get:
      tags:
        - rooms
      summary: Get room entry by name
      operationId: roomGetByName
      parameters:
        - in: path
          name: roomName
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoomEntry'
        '400':
          description: Bad request
        '404':
          description: Room not found
        '500':
          description: Internal server error
  /api/rooms/{roomId}/settings:
    get:
      tags:
        - rooms
      summary: Get room settings
      operationId: roomSettings
      parameters:
        - in: path
          name: roomId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoomSettings'
        '400':
          description: Bad request
        '404':
          description: Room not found
        '500':
          description: Internal server error
  /api/rooms/{roomId}/stats:
    get:
      tags:
        - rooms
      summary: Get room statistics
      operationId: roomStats
      parameters:
        - in: path
          name: roomId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoomStats'
        '404':
          description: Room not found
        '500':
          description: Internal server error
  /api/rooms/{roomId}/stop:
    post:
      tags:
        - rooms
      summary: Stop room
      operationId: roomStop
      parameters:
        - in: path
          name: roomId
          required: true
          schema:
            type: string
      responses:
        '204':
          description: OK
        '404':
          description: Room not found
        '500':
          description: Internal server error
  /api/rooms/{roomId}/start:
    post:
      tags:
        - rooms
      summary: Start room
      operationId: roomStart
      parameters:
        - in: path
          name: roomId
          required: true
          schema:
            type: string
      responses:
        '204':
          description: OK
        '404':
          description: Room not found
        '500':
          description: Internal server error
  /api/rooms/{roomId}/restart:
    post:
      tags:
        - rooms
      summary: Restart room
      operationId: roomRestart
      parameters:
        - in: path
          name: roomId
          required: true
          schema:
            type: string
      responses:
        '204':
          description: OK
        '404':
          description: Room not found
        '500':
          description: Internal server error
  /api/rooms/{roomId}/pause:
    post:
      tags:
        - rooms
      summary: Pause room
      operationId: roomPause
      parameters:
        - in: path
          name: roomId
          required: true
          schema:
            type: string
      responses:
        '204':
          description: OK
        '404':
          description: Room not found
        '500':
          description: Internal server error
  /api/rooms/{roomId}/recreate:
    post:
      tags:
        - rooms
      summary: Recreate room
      operationId: roomRecreate
      parameters:
        - in: path
          name: roomId
          required: true
          schema:
            type: string
        - in: query
          name: start
          required: false
          schema:
            type: boolean
            description: |
              Whether the room should be started or stopped after
              recreation, default is the current state of the room.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RoomSettings'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoomEntry'
        '404':
          description: Room not found
        '500':
          description: Internal server error
  /api/docker-compose.yaml:
    get:
      tags:
        - rooms
      summary: Export room as docker-compose
      operationId: exportAsDockerCompose
      responses:
        '200':
          description: OK
          content:
            application/yaml: {}
        '500':
          description: Internal server error

  /api/pull:
    get:
      tags:
        - default
      summary: Get pull status
      operationId: pullStatus
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PullStatus'
        '500':
          description: Internal server error
    post:
      tags:
        - default
      summary: Start new pull
      operationId: pullStart
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PullStart'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PullStatus'
        '500':
          description: Internal server error
    delete:
      tags:
        - default
      summary: Stop existing pull in progress
      operationId: pullStop
      responses:
        '204':
          description: OK
        '500':
          description: Internal server error
  /api/pull/sse:
    get:
      tags:
        - default
      summary: Get pull status as SSE
      operationId: pullStatusSSE
      responses:
        '200':
          description: OK
          content:
            text/event-stream:
              schema:
                type: array
                format: event-stream
                items:
                  $ref: '#/components/schemas/PullLayer'
        '500':
          description: Internal server error

components:
  schemas:
    RoomsConfig:
      type: object
      properties:
        connections:
          type: number
          example: 100
        neko_images:
          type: array
          items:
            type: string
            example: ghcr.io/m1k1o/neko/firefox:latest
        storage_enabled:
          type: boolean
          example: true
        uses_mux:
          type: boolean
          example: true

    RoomEntry:
      type: object
      properties:
        id:
          type: string
          example: bc04dace10
        url:
          type: string
          example: http://neko-rooms.server.lan/foobar/
        name:
          type: string
          example: foobar
        neko_image:
          type: string
          example: ghcr.io/m1k1o/neko/firefox:latest
        is_outdated:
          type: boolean
          example: true
        max_connections:
          type: number
          example: 10
          description: 0 when using mux
        running:
          type: boolean
          example: true
        paused:
          type: boolean
          example: false
        is_ready:
          type: boolean
          example: true
        status:
          type: string
          example: Up 2 seconds
        created:
          type: string
          format: datetime
          example: "2021-03-07T21:56:34Z"
        labels:
          type: object
          additionalProperties: 
            type: string

    RoomMount:
      type: object
      properties:
        type:
          type: string
          enum: [ private, template, protected, public ]
          example: private
        host_path:
          type: string
          example: /profile
        container_path:
          type: string
          example: /home/neko/.config/chromium

    RoomResources:
      type: object
      properties:
        cpu_shares:
          type: number
          description: relative weight vs. other containers
        nano_cpus:
          type: number
          description: in units of 10^-9 CPUs
        shm_size:
          type: number
          description: in bytes
          default: 2000000000
        memory:
          type: number
          description: in bytes
        gpus:
          type: array
          items:
            type: string
            example: all
        devices:
          type: array
          items:
            type: string
            example: /dev/dri/renderD128

    RoomSettings:
      type: object
      properties:
        api_version:
          type: number
          description: if not set, version is taken from neko_image
        name:
          type: string
          example: foobar
        neko_image:
          type: string
          example: ghcr.io/m1k1o/neko/firefox:latest
        max_connections:
          type: number
          default: 10
          description: 0 when using mux
        user_pass:
          type: string
          example: neko
        admin_pass:
          type: string
          example: admin
        control_protection:
          type: boolean
          example: true
        implicit_control:
          type: boolean
          example: true
        broadcast_pipeline:
          type: string
        screen:
          type: string
          example: 1920x1080@60
        video_codec:
          type: string
          example: VP8
        video_bitrate:
          type: number
          example: 3072
        video_pipeline:
          type: string
        video_max_fps:
          type: number
          example: 25
        audio_codec:
          type: string
          example: OPUS
        audio_bitrate:
          type: number
          example: 128
        audio_pipeline:
          type: string
        envs:
          type: object
          additionalProperties: 
            type: string
          example:
            CUSTOM_ENV: custom value
        labels:
          type: object
          additionalProperties: 
            type: string
        mounts:
          type: array
          items:
            $ref: '#/components/schemas/RoomMount'
        resources:
          $ref: '#/components/schemas/RoomResources'
        hostname:
          type: string
          example: server.lan
        dns:
          type: array
          items:
            type: string
            example: 1.1.1.1
        browser_policy:
          $ref: '#/components/schemas/BrowserPolicy'

    RoomStats:
      type: object
      properties:
        connections:
          type: number
          example: 3
        host:
          type: string
          example: foobar
        members:
          type: array
          items:
            $ref: '#/components/schemas/RoomMember'
        banned:
          type: object
          additionalProperties: 
            type: string
          example:
            192.168.1.8: session_id
        locked:
          type: object
          additionalProperties: 
            type: string
          example:
            control: session_id
            login: session_id
        server_started_at:
          type: string
          format: datetime
          example: "2021-03-07T21:56:34Z"
        last_admin_left_at:
          type: string
          nullable: true
          format: datetime
          example: null
        last_user_left_at:
          type: string
          nullable: true
          format: datetime
          example: "2021-03-07T21:56:34Z"
        control_protection:
          type: boolean
          example: true
        implicit_control:
          type: boolean
          example: true

    RoomMember:
      type: object
      properties:
        id:
          type: string
          example: foobar
        displayname:
          type: string
          example: Foo Bar
        admin:
          type: boolean
          example: true
        muted:
          type: boolean
          example: false

    BrowserPolicy:
      type: object
      properties:
        type:
          type: string
          enum: [ firefox, chromium ]
        path:
          type: string
          example: /usr/lib/firefox/distribution/policies.json
        content:
          $ref: '#/components/schemas/BrowserPolicyContent'

    BrowserPolicyContent:
      type: object
      properties:
        extensions:
          type: array
          items:
            $ref: '#/components/schemas/BrowserPolicyExtension'
        developer_tools:
          type: boolean
          example: true
        persistent_data:
          type: boolean
          example: false
    
    BrowserPolicyExtension:
      type: object
      properties:
        id:
          type: string
          example: uBlock0@raymondhill.net
        url:
          type: string
          example: https://addons.mozilla.org/firefox/downloads/latest/ublock-origin/latest.xpi

    PullStart:
      type: object
      properties:
        neko_image:
          type: string
          example: ghcr.io/m1k1o/neko/firefox:latest
        registry_user:
          type: string
        registry_pass:
          type: string

    PullLayer:
      type: object
      properties:
        status:
          type: string
          example: ghcr.io/m1k1o/neko/firefox:latest
        progressDetail:
          type: object
          properties:
            current:
              type: number
            total:
              type: number
        progress:
          type: string
        id:
          type: string

    PullStatus:
      type: object
      properties:
        active:
          type: boolean
          example: true
        started:
          type: string
          format: datetime
          example: "2021-03-07T21:56:34Z"
        layers:
          type: array
          items:
            $ref: '#/components/schemas/PullLayer'
        status:
          type: array
          items:
            type: string
        finished:
          type: string
          format: datetime
          example: "2021-03-07T21:56:34Z"