openapi: "3.0.0"
info:
  description: "Remote control and stream data from Pupil Invisible Companion"
  version: "1.1.0"
  title: "Pupil Labs Invisible Companion Realtime API"
servers:
  - url: http://pi.local:8080/api
    description: Pupil Invisible default server URL
paths:
  /status:
    get:
      tags:
        - status
      summary: "phone status; upgrade to websocket connection; updates about Phone/Sensor/Recording/NetworkDevice/Event updates"
      description: ""
      responses:
        "200":
          description: "phone status"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusEnvelope"
        "101":
          description: "upgrade to websocket, send updates for Phone/Sensor/Recording/NetworkDevice/Event"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Status"

  /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"

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