openapi: 3.0.0
info:
  description: Remote control and stream data from Pupil Invisible Companion
  version: 2.1.0
  title: Pupil Labs Neon Companion Realtime API
servers:
  - url: http://neon.local:8080/api
    description: Neon device server
paths:
  /status:
    get:
      tags:
        - status
      summary: >-
        phone status; upgrade to websocket connection; updates about
        Phone/Sensor/Recording/NetworkDevice/Event updates
      description: ""
      responses:
        "101":
          description: >-
            upgrade to websocket, send updates for
            Phone/Sensor/Recording/NetworkDevice/Event
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Status"
        "200":
          description: phone status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusEnvelope"
  /recording:start:
    post:
      tags:
        - recording
      summary: start recording
      description: ""
      responses:
        "200":
          description: recording started
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RecordingStartEnvelope"
        "500":
          description: >-
            recording start failed <br />Possible errors: <br /> - Recording
            running <br /> - Template has required fields <br /> - Low battery
            <br /> - Low storage <br /> - No wearer selected <br /> - No
            workspace selected <br /> - Setup bottom sheets not completed
  /recording:stop_and_save:
    post:
      tags:
        - recording
      summary: stop and save recording
      description: >-
        stop and save recording, only possible if template has no required
        fields
      responses:
        "200":
          description: recording stopped and saved
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RecordingStopEnvelope"
        "500":
          description: >-
            recording stop and save failed <br />Possible errors: <br /> -
            Recording not running <br /> - template has required fields
  /recording:cancel:
    post:
      tags:
        - recording
      summary: cancel recording
      description: cancel recording
      responses:
        "200":
          description: recording stopped and discarded
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RecordingCancelEnvelope"
        "500":
          description: >-
            recording cancel failed <br />Possible errors: <br /> - Recording
            not running
  /event:
    post:
      tags:
        - events
      requestBody:
        description: recording event
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EventPost"
      summary: create recording event
      description: ""
      responses:
        "200":
          description: recording event added
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EventEnvelope"
  /template_def:
    get:
      tags:
        - templates
      responses:
        "200":
          description: active template definition
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TemplateDefEnvelope"
      summary: get template definition
      description: ""
  /template_data:
    get:
      tags:
        - templates
      responses:
        "200":
          description: |
            returns active template data, in format:
            ```json
            {
              "question_uuid": ["one answer"],
              "question_uuid": ["one", "or", "more", "answers"],
              "question_uuid": ["5"],
            }
            ```
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TemplateDataEnvelope"
      summary: get template data
      description: ""
    post:
      tags:
        - templates
      requestBody:
        description: |
          set template data, using format:
            ```json
            {
              "question_uuid": ["one answer"],
              "question_uuid": ["one", "or", "more", "answers"],
              "question_uuid": ["5"],
            }
            ```
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TemplateData"
      responses:
        "200":
          description: filled template data
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TemplateDataEnvelope"
        "404":
          description: Field ID not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TemplateDataEnvelope"
components:
  schemas:
    Envelope:
      type: object
      properties:
        message:
          type: string
        result:
          type: object
      discriminator:
        propertyName: envelope_message
    Status:
      properties:
        model:
          type: string
        data:
          type: object
          oneOf:
            - $ref: "#/components/schemas/Event"
            - $ref: "#/components/schemas/Recording"
            - $ref: "#/components/schemas/NetworkDevice"
            - $ref: "#/components/schemas/Sensor"
            - $ref: "#/components/schemas/Phone"
    StatusEnvelope:
      allOf:
        - $ref: "#/components/schemas/Envelope"
        - type: object
          properties:
            result:
              type: array
              items:
                $ref: "#/components/schemas/Status"
    Phone:
      properties:
        ip:
          type: string
          format: ip
          readOnly: true
        port:
          type: number
          readOnly: true
        device_id:
          type: string
          readOnly: true
        device_name:
          type: string
          readOnly: true
        battery_level:
          type: number
          readOnly: true
        battery_state:
          type: string
          enum:
            - OK
            - LOW
            - CRITICAL
          readOnly: true
        memory:
          type: number
          readOnly: true
        memory_state:
          type: string
          enum:
            - OK
            - LOW
            - CRITICAL
          readOnly: true
        time_echo_port:
          type: integer
          readOnly: true
    Hardware:
      properties:
        version:
          type: string
        world_camera_serial:
          type: string
          readOnly: true
        glasses_serial:
          type: string
          readOnly: true
    NetworkDevice:
      properties:
        ip:
          type: string
          format: ip
          readOnly: true
        device_id:
          type: string
          readOnly: true
        device_name:
          type: string
          readOnly: true
        connected:
          type: boolean
          readOnly: true
    RecordingStart:
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
    RecordingStartEnvelope:
      allOf:
        - $ref: "#/components/schemas/Envelope"
        - type: object
          properties:
            result:
              $ref: "#/components/schemas/RecordingStart"
    RecordingStop:
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        rec_duration_ns:
          type: integer
          description: Recording duration ns
          readOnly: true
    RecordingStopEnvelope:
      allOf:
        - $ref: "#/components/schemas/Envelope"
        - type: object
          properties:
            result:
              $ref: "#/components/schemas/RecordingStop"
    Recording:
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        rec_duration_ns:
          type: integer
        message:
          type: string
        action:
          type: string
          enum:
            - START
            - STOP
            - SAVE
            - DISCARD
            - ERROR
    RecordingCancel:
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
    RecordingCancelEnvelope:
      allOf:
        - $ref: "#/components/schemas/Envelope"
        - type: object
          properties:
            result:
              $ref: "#/components/schemas/RecordingCancel"
    Event:
      properties:
        name:
          type: string
        timestamp:
          type: integer
          format: int64
        recording_id:
          type: string
          format: uuid
          readOnly: true
      example:
        timestamp: 1643899966134527000
        recording_id: 123e4567-e89b-12d3-a456-426614174000
    EventPost:
      properties:
        name:
          type: string
        timestamp:
          type: integer
          format: int64
      example:
        name: send event
        timestamp: 1643899966134527000
    EventEnvelope:
      allOf:
        - $ref: "#/components/schemas/Envelope"
        - type: object
          properties:
            result:
              $ref: "#/components/schemas/Event"
    Sensor:
      type: object
      properties:
        sensor:
          type: string
          enum:
            - world
            - gaze
        conn_type:
          type: string
          enum:
            - DIRECT
            - WEBSOCKET
        protocol:
          type: string
          readOnly: true
        ip:
          type: string
          readOnly: true
        port:
          type: integer
          readOnly: true
        params:
          type: string
          readOnly: true
        connected:
          type: boolean
          readOnly: true
      example:
        sensor: world
        protocol: rtsp
        ip: 192.168.2.101
        port: 8686
        params: camera=world
        connected: true
    TemplateItem:
      type: object
      required:
        - widget_type
      additionalProperties: false
      properties:
        choices:
          type: array
          items:
            type: string

        help_text:
          description: short optional help text for the item
          type: string
        id:
          example: 00000000-0000-0000-0000-000000000000
          format: uuid
          type: string
        input_type:
          default: any
          description: the basic type of the value for this item's input
          enum:
            - any
            - integer
            - float
          type: string
        required:
          description: if value is required
          type: boolean
        title:
          description: title of item
          type: string
        widget_type:
          description: widget to use for this item
          enum:
            - TEXT
            - PARAGRAPH
            - RADIO_LIST
            - CHECKBOX_LIST
            - SECTION_HEADER
            - PAGE_BREAK
          type: string

    Template:
      additionalProperties: false
      properties:
        archived_at:
          format: date-time
          type: string
        created_at:
          format: date-time
          type: string
        description:
          type: string
        id:
          example: 00000000-0000-0000-0000-000000000000
          format: uuid
          type: string
        is_default_template:
          readOnly: true
          type: boolean
        items:
          items:
            $ref: "#/components/schemas/TemplateItem"
            type: object
          type: array
        label_ids:
          default: []
          items:
            example: 00000000-0000-0000-0000-000000000000
            format: uuid
            type: string
          readOnly: true
          type: array
        name:
          type: string
        published_at:
          format: date-time
          type: string
        recording_ids:
          default: []
          items:
            example: 00000000-0000-0000-0000-000000000000
            format: uuid
            type: string
          readOnly: true
          type: array
        recording_name_format:
          items:
            type: string
          type: array
        updated_at:
          format: date-time
          type: string
      required:
        - name
      type: object
    TemplateDefEnvelope:
      allOf:
        - $ref: "#/components/schemas/Envelope"
        - type: object
          properties:
            result:
              type: array
              items:
                $ref: "#/components/schemas/Template"
    TemplateData:
      type: object
      additionalProperties:
        type: array
        items:
          type: string
      example:
        f904ebe5-39f4-40c3-85cf-ba36a4d93805: ["answer"]
        467a7b8c-ddbe-4315-ae3b-f36e8c7c29de: ["multiple", "choice"]
    TemplateDataEnvelope:
      allOf:
        - $ref: "#/components/schemas/Envelope"
        - type: object
          properties:
            result:
              type: object
              $ref: "#/components/schemas/TemplateData"