asyncapi: 3.0.0
info:
  title: MyCirrus API - Live data and status
  version: 1.0.0
  description: API documentation for the MyCirrus API
  contact:
    name: Support
    url: https://www.cirrusresearch.com/support/
    email: support@cirrusresearch.com
  license:
    name: MIT
  termsOfService: https://mycirrus.cloud/static/termsAndConditions.html
defaultContentType: application/json
servers:
  production:
    host: api.mycirrus.cloud
    pathname: /v1
    protocol: wss
    description: Production server
    security:
      - type: httpApiKey
        in: header
        name: X-Api-Key
        description: >-
          To access the API you must authenticate using a custom key created via
          the API console.


          The key should be passed in the X-Api-Key header.<br>

          For Example: `X-Api-Key: mycirrus-123456-AABBCCDD11223344`.


          To create a key, go to the [API
          console](https://mycirrus.cloud/developer-api) and click the "Create
          API key" button.


          When creating an API key you must choose the permissions for that key.
          These scopes control what the key can access:

          * `instruments:read` - Allows read access to instruments and related
          information

          * `instruments:write` - Allows write access to instruments and related
          information

          * `instruments:action` - Allows actions to be performed on instruments

          * `data.live:read` - Allows read access to live data

          * `data.noise:read` - Allows read access to noise data

          * `data.enviro:read` - Allows read access to environmental data
          (weather, particulates, gases, vibration)

          * `data.events:read` - Allows read access to event data

          * `data.audio:read` - Allows read access to audio data

          * `data.system:read` - Allows read access to system health data
          (calibrations, SIC, monitor stats)

          * `webhooks:read` - Allows read access to webhooks

          * `webhooks:write` - Allows write access to webhooks
channels:
  liveChannel:
    title: Live data and status channel
    address: live/{instrument}
    messages:
      LiveData:
        payload:
          type: object
          properties:
            type:
              type: string
              enum:
                - LiveData
              description: Type of message
            time:
              type: string
              format: date-time
              description: Time of the data
            values:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                    description: Name of the value
                  value:
                    type: number
                    description: The value in dB
              description: List of live data values
          example:
            type: LiveData
            time: '2020-01-01T00:00:00Z'
            values:
              - name: LAeq
                value: 52.3
              - name: LCPeak
                value: 63.4
      InstrumentStatus:
        payload:
          type: object
          properties:
            type:
              type: string
              enum:
                - InstrumentStatus
              description: Type of message
            time:
              type: string
              format: date-time
              description: Time of the status
            online:
              type: boolean
              description: True if the instrument is online, otherwise false
            measuring:
              type: boolean
              description: True if the instrument is measuring, otherwise false
            calibrationInProgress:
              type: boolean
              description: >-
                True if the instrument is performing a calibration, otherwise
                false
            sicInProgress:
              type: boolean
              description: >-
                True if the instrument is performing a System Integrity Check
                (SIC), otherwise false
          example:
            type: InstrumentStatus
            time: '2020-01-01T00:00:00Z'
            online: true
            measuring: true
            calibrationInProgress: false
            sicInProgress: false
      ActionStatus:
        payload:
          type: object
          properties:
            type:
              type: string
              enum:
                - ActionStatus
              description: Type of message
            time:
              type: string
              format: date-time
              description: Time of the status
            action:
              type: string
              enum:
                - Identify
                - Calibration
                - SIC
              description: Action that was performed
            status:
              type: string
              enum:
                - InProgress
                - Success
                - Failed
              description: Status of the action
            error:
              oneOf:
                - type: 'null'
                - type: string
              description: May contain additional error message if status is Failed
            data:
              oneOf:
                - type: 'null'
                - title: CalibrationStatus
                  type: object
                  description: Status of the Calibration
                  examples:
                    - time: '2020-01-01T00:00:00Z'
                      status: Success
                      level: 93.7
                      offset: 0.04
                  properties:
                    time:
                      type: string
                      format: date-time
                      description: Time of the calibration
                    status:
                      type: string
                      description: Status of the calibration
                    level:
                      type: number
                      description: The calibration level in dB
                    offset:
                      type: number
                      description: The offset from factory calibration in dB
                - title: SicStatus
                  type: object
                  description: Status of the System Integrity Check (SIC)
                  examples:
                    - time: '2020-01-01T00:00:00Z'
                      status: Success
                      _500hz: 98
                      _1khz: 98
                      _8khz: 98
                  properties:
                    time:
                      type: string
                      format: date-time
                      description: Time of the SIC result
                    status:
                      type: string
                      description: Status of the SIC
                    _500Hz:
                      type: number
                      description: The 500 Hz level in dB
                    _1KHz:
                      type: number
                      description: The 1 kHz level in dB
                    _8KHz:
                      type: number
                      description: The 8 kHz level in dB
          example:
            type: ActionStatus
            time: '2020-01-01T00:00:00Z'
            action: Identify
            status: InProgress
      Error:
        payload:
          type: object
          properties:
            error:
              type: string
              description: Error code
            description:
              type: string
              description: Description of the error
          example:
            error: InvalidAction
            description: Unknown action (X)
      KeepAlive:
        description: >-
          The connection will timeout after 1 minute of inactivity.<br>

          To keep the connection alive, send a KeepAlive message every 30
          seconds.


          The server will respond with another KeepAlive message.
        payload:
          type: object
          properties:
            action:
              type: string
              enum:
                - KeepAlive
              description: Action to perform
          example:
            action: KeepAlive
      DoAction:
        payload:
          type: object
          properties:
            action:
              type: string
              enum:
                - Identify
                - Calibration
                - SIC
              description: Action to perform
          example:
            action: Identify
        description: |-
          Perform an action on the instrument.

          The possible actions are:
          - Identify
            - The instrument will flash its LED.
          - Calibration
            - The instrument will start the calibration process. You will need to attach an acoustic calibrator to the instrument.
          - SIC
            - The instrument will perform a System Integrity Check (SIC).

          &nbsp;

          Requires an API key with the `instruments:action` scope.
      StartStopLiveData:
        payload:
          type: object
          properties:
            action:
              type: string
              enum:
                - StartLiveData
                - StopLiveData
              description: Action to perform
            types:
              type: array
              items:
                type: string
              description: List of requested live data types
          example:
            action: StartLiveData
            types:
              - LAeq
              - LCPeak
        description: >-
          Start or stop live data.


          If you specify the `StartLiveData` action the server will start
          sending live data for the specified types.<br>

          If the server is already sending live data, the types will be updated.


          If you specify the `StopLiveData` action the server will stop sending
          live data.


          The possible live data types are:

          - Leq
            - LAeq, LCeq, LZeq, LAeqI
            - LAeqT
          - Peak
            - LAPeak, LCPeak, LZPeak
          - SPL
            - LAF, LAS, LAI
            - LCF, LCS, LCI
            - LZF, LZS, LZI
          - Statistical Levels
            -  Ln1, Ln5, Ln10, Ln50, Ln90, Ln95, Ln99
          - Moving Average
            - Examples: LAeq,5m, LAeq,60m
            - _Available values dependant on settings_
          - Octaves
            - 31.5Hz, 63Hz, 125Hz, 250Hz, 500Hz, 1KHz, 2KHz, 4KHz, 8KHz, 16KHz
          - Third Octaves
            - 6.3Hz3 to 20KHz3
            - _Names end with 3 to differentiate from octave bands_

          &nbsp;


          Some types may be unavailable depending on subscription plan.<br>

          If you specify an invalid or unavailable type, the server will ignore
          it.<br>

          If all specified types are invalid or no types are specified, the
          server will respond with an error.


          Requires an API key with the `data.live:read` scope.
    description: >-
      Live data, status updates and actions


      Only online noise instruments are supported through this API. If an
      instrument is online you can connect the websocket, if the instrument goes
      offline the websocket will be closed.


      Requires an API key with the `instruments:read` scope to make the
      connection and begin receiving status updates. Other actions require
      additional scopes.
    parameters:
      instrument:
        description: The serial number of the instrument
        examples:
          - QT123456
    bindings:
      ws:
        headers:
          - type: object
            properties:
              X-Api-Key:
                type: string
                description: API key
operations:
  receiveUpdate:
    title: Receive live data and status updates
    action: receive
    channel:
      title: Live data and status channel
      address: live/{instrument}
      messages:
        LiveData:
          payload:
            type: object
            properties:
              type:
                type: string
                enum:
                  - LiveData
                description: Type of message
              time:
                type: string
                format: date-time
                description: Time of the data
              values:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                      description: Name of the value
                    value:
                      type: number
                      description: The value in dB
                description: List of live data values
            example:
              type: LiveData
              time: '2020-01-01T00:00:00Z'
              values:
                - name: LAeq
                  value: 52.3
                - name: LCPeak
                  value: 63.4
        InstrumentStatus:
          payload:
            type: object
            properties:
              type:
                type: string
                enum:
                  - InstrumentStatus
                description: Type of message
              time:
                type: string
                format: date-time
                description: Time of the status
              online:
                type: boolean
                description: True if the instrument is online, otherwise false
              measuring:
                type: boolean
                description: True if the instrument is measuring, otherwise false
              calibrationInProgress:
                type: boolean
                description: >-
                  True if the instrument is performing a calibration, otherwise
                  false
              sicInProgress:
                type: boolean
                description: >-
                  True if the instrument is performing a System Integrity Check
                  (SIC), otherwise false
            example:
              type: InstrumentStatus
              time: '2020-01-01T00:00:00Z'
              online: true
              measuring: true
              calibrationInProgress: false
              sicInProgress: false
        ActionStatus:
          payload:
            type: object
            properties:
              type:
                type: string
                enum:
                  - ActionStatus
                description: Type of message
              time:
                type: string
                format: date-time
                description: Time of the status
              action:
                type: string
                enum:
                  - Identify
                  - Calibration
                  - SIC
                description: Action that was performed
              status:
                type: string
                enum:
                  - InProgress
                  - Success
                  - Failed
                description: Status of the action
              error:
                oneOf:
                  - type: 'null'
                  - type: string
                description: May contain additional error message if status is Failed
              data:
                oneOf:
                  - type: 'null'
                  - title: CalibrationStatus
                    type: object
                    description: Status of the Calibration
                    examples:
                      - time: '2020-01-01T00:00:00Z'
                        status: Success
                        level: 93.7
                        offset: 0.04
                    properties:
                      time:
                        type: string
                        format: date-time
                        description: Time of the calibration
                      status:
                        type: string
                        description: Status of the calibration
                      level:
                        type: number
                        description: The calibration level in dB
                      offset:
                        type: number
                        description: The offset from factory calibration in dB
                  - title: SicStatus
                    type: object
                    description: Status of the System Integrity Check (SIC)
                    examples:
                      - time: '2020-01-01T00:00:00Z'
                        status: Success
                        _500hz: 98
                        _1khz: 98
                        _8khz: 98
                    properties:
                      time:
                        type: string
                        format: date-time
                        description: Time of the SIC result
                      status:
                        type: string
                        description: Status of the SIC
                      _500Hz:
                        type: number
                        description: The 500 Hz level in dB
                      _1KHz:
                        type: number
                        description: The 1 kHz level in dB
                      _8KHz:
                        type: number
                        description: The 8 kHz level in dB
            example:
              type: ActionStatus
              time: '2020-01-01T00:00:00Z'
              action: Identify
              status: InProgress
        Error:
          payload:
            type: object
            properties:
              error:
                type: string
                description: Error code
              description:
                type: string
                description: Description of the error
            example:
              error: InvalidAction
              description: Unknown action (X)
        KeepAlive:
          description: >-
            The connection will timeout after 1 minute of inactivity.<br>

            To keep the connection alive, send a KeepAlive message every 30
            seconds.


            The server will respond with another KeepAlive message.
          payload:
            type: object
            properties:
              action:
                type: string
                enum:
                  - KeepAlive
                description: Action to perform
            example:
              action: KeepAlive
        DoAction:
          payload:
            type: object
            properties:
              action:
                type: string
                enum:
                  - Identify
                  - Calibration
                  - SIC
                description: Action to perform
            example:
              action: Identify
          description: |-
            Perform an action on the instrument.

            The possible actions are:
            - Identify
              - The instrument will flash its LED.
            - Calibration
              - The instrument will start the calibration process. You will need to attach an acoustic calibrator to the instrument.
            - SIC
              - The instrument will perform a System Integrity Check (SIC).

            &nbsp;

            Requires an API key with the `instruments:action` scope.
        StartStopLiveData:
          payload:
            type: object
            properties:
              action:
                type: string
                enum:
                  - StartLiveData
                  - StopLiveData
                description: Action to perform
              types:
                type: array
                items:
                  type: string
                description: List of requested live data types
            example:
              action: StartLiveData
              types:
                - LAeq
                - LCPeak
          description: >-
            Start or stop live data.


            If you specify the `StartLiveData` action the server will start
            sending live data for the specified types.<br>

            If the server is already sending live data, the types will be
            updated.


            If you specify the `StopLiveData` action the server will stop
            sending live data.


            The possible live data types are:

            - Leq
              - LAeq, LCeq, LZeq, LAeqI
              - LAeqT
            - Peak
              - LAPeak, LCPeak, LZPeak
            - SPL
              - LAF, LAS, LAI
              - LCF, LCS, LCI
              - LZF, LZS, LZI
            - Statistical Levels
              -  Ln1, Ln5, Ln10, Ln50, Ln90, Ln95, Ln99
            - Moving Average
              - Examples: LAeq,5m, LAeq,60m
              - _Available values dependant on settings_
            - Octaves
              - 31.5Hz, 63Hz, 125Hz, 250Hz, 500Hz, 1KHz, 2KHz, 4KHz, 8KHz, 16KHz
            - Third Octaves
              - 6.3Hz3 to 20KHz3
              - _Names end with 3 to differentiate from octave bands_

            &nbsp;


            Some types may be unavailable depending on subscription plan.<br>

            If you specify an invalid or unavailable type, the server will
            ignore it.<br>

            If all specified types are invalid or no types are specified, the
            server will respond with an error.


            Requires an API key with the `data.live:read` scope.
      description: >-
        Live data, status updates and actions


        Only online noise instruments are supported through this API. If an
        instrument is online you can connect the websocket, if the instrument
        goes offline the websocket will be closed.


        Requires an API key with the `instruments:read` scope to make the
        connection and begin receiving status updates. Other actions require
        additional scopes.
      parameters:
        instrument:
          description: The serial number of the instrument
          examples:
            - QT123456
      bindings:
        ws:
          headers:
            - type: object
              properties:
                X-Api-Key:
                  type: string
                  description: API key
    summary: Receive live data and status updates
    description: Receive live data and status updates.
    tags:
      - name: Live data and status
    messages:
      - payload:
          type: object
          properties:
            type:
              type: string
              enum:
                - LiveData
              description: Type of message
            time:
              type: string
              format: date-time
              description: Time of the data
            values:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                    description: Name of the value
                  value:
                    type: number
                    description: The value in dB
              description: List of live data values
          example:
            type: LiveData
            time: '2020-01-01T00:00:00Z'
            values:
              - name: LAeq
                value: 52.3
              - name: LCPeak
                value: 63.4
      - payload:
          type: object
          properties:
            type:
              type: string
              enum:
                - InstrumentStatus
              description: Type of message
            time:
              type: string
              format: date-time
              description: Time of the status
            online:
              type: boolean
              description: True if the instrument is online, otherwise false
            measuring:
              type: boolean
              description: True if the instrument is measuring, otherwise false
            calibrationInProgress:
              type: boolean
              description: >-
                True if the instrument is performing a calibration, otherwise
                false
            sicInProgress:
              type: boolean
              description: >-
                True if the instrument is performing a System Integrity Check
                (SIC), otherwise false
          example:
            type: InstrumentStatus
            time: '2020-01-01T00:00:00Z'
            online: true
            measuring: true
            calibrationInProgress: false
            sicInProgress: false
      - payload:
          type: object
          properties:
            type:
              type: string
              enum:
                - ActionStatus
              description: Type of message
            time:
              type: string
              format: date-time
              description: Time of the status
            action:
              type: string
              enum:
                - Identify
                - Calibration
                - SIC
              description: Action that was performed
            status:
              type: string
              enum:
                - InProgress
                - Success
                - Failed
              description: Status of the action
            error:
              oneOf:
                - type: 'null'
                - type: string
              description: May contain additional error message if status is Failed
            data:
              oneOf:
                - type: 'null'
                - title: CalibrationStatus
                  type: object
                  description: Status of the Calibration
                  examples:
                    - time: '2020-01-01T00:00:00Z'
                      status: Success
                      level: 93.7
                      offset: 0.04
                  properties:
                    time:
                      type: string
                      format: date-time
                      description: Time of the calibration
                    status:
                      type: string
                      description: Status of the calibration
                    level:
                      type: number
                      description: The calibration level in dB
                    offset:
                      type: number
                      description: The offset from factory calibration in dB
                - title: SicStatus
                  type: object
                  description: Status of the System Integrity Check (SIC)
                  examples:
                    - time: '2020-01-01T00:00:00Z'
                      status: Success
                      _500hz: 98
                      _1khz: 98
                      _8khz: 98
                  properties:
                    time:
                      type: string
                      format: date-time
                      description: Time of the SIC result
                    status:
                      type: string
                      description: Status of the SIC
                    _500Hz:
                      type: number
                      description: The 500 Hz level in dB
                    _1KHz:
                      type: number
                      description: The 1 kHz level in dB
                    _8KHz:
                      type: number
                      description: The 8 kHz level in dB
          example:
            type: ActionStatus
            time: '2020-01-01T00:00:00Z'
            action: Identify
            status: InProgress
      - payload:
          type: object
          properties:
            error:
              type: string
              description: Error code
            description:
              type: string
              description: Description of the error
          example:
            error: InvalidAction
            description: Unknown action (X)
      - description: >-
          The connection will timeout after 1 minute of inactivity.<br>

          To keep the connection alive, send a KeepAlive message every 30
          seconds.


          The server will respond with another KeepAlive message.
        payload:
          type: object
          properties:
            action:
              type: string
              enum:
                - KeepAlive
              description: Action to perform
          example:
            action: KeepAlive
  sendCommand:
    title: Start actions and live data
    action: send
    channel:
      title: Live data and status channel
      address: live/{instrument}
      messages:
        LiveData:
          payload:
            type: object
            properties:
              type:
                type: string
                enum:
                  - LiveData
                description: Type of message
              time:
                type: string
                format: date-time
                description: Time of the data
              values:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                      description: Name of the value
                    value:
                      type: number
                      description: The value in dB
                description: List of live data values
            example:
              type: LiveData
              time: '2020-01-01T00:00:00Z'
              values:
                - name: LAeq
                  value: 52.3
                - name: LCPeak
                  value: 63.4
        InstrumentStatus:
          payload:
            type: object
            properties:
              type:
                type: string
                enum:
                  - InstrumentStatus
                description: Type of message
              time:
                type: string
                format: date-time
                description: Time of the status
              online:
                type: boolean
                description: True if the instrument is online, otherwise false
              measuring:
                type: boolean
                description: True if the instrument is measuring, otherwise false
              calibrationInProgress:
                type: boolean
                description: >-
                  True if the instrument is performing a calibration, otherwise
                  false
              sicInProgress:
                type: boolean
                description: >-
                  True if the instrument is performing a System Integrity Check
                  (SIC), otherwise false
            example:
              type: InstrumentStatus
              time: '2020-01-01T00:00:00Z'
              online: true
              measuring: true
              calibrationInProgress: false
              sicInProgress: false
        ActionStatus:
          payload:
            type: object
            properties:
              type:
                type: string
                enum:
                  - ActionStatus
                description: Type of message
              time:
                type: string
                format: date-time
                description: Time of the status
              action:
                type: string
                enum:
                  - Identify
                  - Calibration
                  - SIC
                description: Action that was performed
              status:
                type: string
                enum:
                  - InProgress
                  - Success
                  - Failed
                description: Status of the action
              error:
                oneOf:
                  - type: 'null'
                  - type: string
                description: May contain additional error message if status is Failed
              data:
                oneOf:
                  - type: 'null'
                  - title: CalibrationStatus
                    type: object
                    description: Status of the Calibration
                    examples:
                      - time: '2020-01-01T00:00:00Z'
                        status: Success
                        level: 93.7
                        offset: 0.04
                    properties:
                      time:
                        type: string
                        format: date-time
                        description: Time of the calibration
                      status:
                        type: string
                        description: Status of the calibration
                      level:
                        type: number
                        description: The calibration level in dB
                      offset:
                        type: number
                        description: The offset from factory calibration in dB
                  - title: SicStatus
                    type: object
                    description: Status of the System Integrity Check (SIC)
                    examples:
                      - time: '2020-01-01T00:00:00Z'
                        status: Success
                        _500hz: 98
                        _1khz: 98
                        _8khz: 98
                    properties:
                      time:
                        type: string
                        format: date-time
                        description: Time of the SIC result
                      status:
                        type: string
                        description: Status of the SIC
                      _500Hz:
                        type: number
                        description: The 500 Hz level in dB
                      _1KHz:
                        type: number
                        description: The 1 kHz level in dB
                      _8KHz:
                        type: number
                        description: The 8 kHz level in dB
            example:
              type: ActionStatus
              time: '2020-01-01T00:00:00Z'
              action: Identify
              status: InProgress
        Error:
          payload:
            type: object
            properties:
              error:
                type: string
                description: Error code
              description:
                type: string
                description: Description of the error
            example:
              error: InvalidAction
              description: Unknown action (X)
        KeepAlive:
          description: >-
            The connection will timeout after 1 minute of inactivity.<br>

            To keep the connection alive, send a KeepAlive message every 30
            seconds.


            The server will respond with another KeepAlive message.
          payload:
            type: object
            properties:
              action:
                type: string
                enum:
                  - KeepAlive
                description: Action to perform
            example:
              action: KeepAlive
        DoAction:
          payload:
            type: object
            properties:
              action:
                type: string
                enum:
                  - Identify
                  - Calibration
                  - SIC
                description: Action to perform
            example:
              action: Identify
          description: |-
            Perform an action on the instrument.

            The possible actions are:
            - Identify
              - The instrument will flash its LED.
            - Calibration
              - The instrument will start the calibration process. You will need to attach an acoustic calibrator to the instrument.
            - SIC
              - The instrument will perform a System Integrity Check (SIC).

            &nbsp;

            Requires an API key with the `instruments:action` scope.
        StartStopLiveData:
          payload:
            type: object
            properties:
              action:
                type: string
                enum:
                  - StartLiveData
                  - StopLiveData
                description: Action to perform
              types:
                type: array
                items:
                  type: string
                description: List of requested live data types
            example:
              action: StartLiveData
              types:
                - LAeq
                - LCPeak
          description: >-
            Start or stop live data.


            If you specify the `StartLiveData` action the server will start
            sending live data for the specified types.<br>

            If the server is already sending live data, the types will be
            updated.


            If you specify the `StopLiveData` action the server will stop
            sending live data.


            The possible live data types are:

            - Leq
              - LAeq, LCeq, LZeq, LAeqI
              - LAeqT
            - Peak
              - LAPeak, LCPeak, LZPeak
            - SPL
              - LAF, LAS, LAI
              - LCF, LCS, LCI
              - LZF, LZS, LZI
            - Statistical Levels
              -  Ln1, Ln5, Ln10, Ln50, Ln90, Ln95, Ln99
            - Moving Average
              - Examples: LAeq,5m, LAeq,60m
              - _Available values dependant on settings_
            - Octaves
              - 31.5Hz, 63Hz, 125Hz, 250Hz, 500Hz, 1KHz, 2KHz, 4KHz, 8KHz, 16KHz
            - Third Octaves
              - 6.3Hz3 to 20KHz3
              - _Names end with 3 to differentiate from octave bands_

            &nbsp;


            Some types may be unavailable depending on subscription plan.<br>

            If you specify an invalid or unavailable type, the server will
            ignore it.<br>

            If all specified types are invalid or no types are specified, the
            server will respond with an error.


            Requires an API key with the `data.live:read` scope.
      description: >-
        Live data, status updates and actions


        Only online noise instruments are supported through this API. If an
        instrument is online you can connect the websocket, if the instrument
        goes offline the websocket will be closed.


        Requires an API key with the `instruments:read` scope to make the
        connection and begin receiving status updates. Other actions require
        additional scopes.
      parameters:
        instrument:
          description: The serial number of the instrument
          examples:
            - QT123456
      bindings:
        ws:
          headers:
            - type: object
              properties:
                X-Api-Key:
                  type: string
                  description: API key
    summary: Start actions and live data
    description: Start an action or start/stop live data.
    tags:
      - name: Live data and status
    messages:
      - payload:
          type: object
          properties:
            action:
              type: string
              enum:
                - Identify
                - Calibration
                - SIC
              description: Action to perform
          example:
            action: Identify
        description: |-
          Perform an action on the instrument.

          The possible actions are:
          - Identify
            - The instrument will flash its LED.
          - Calibration
            - The instrument will start the calibration process. You will need to attach an acoustic calibrator to the instrument.
          - SIC
            - The instrument will perform a System Integrity Check (SIC).

          &nbsp;

          Requires an API key with the `instruments:action` scope.
      - payload:
          type: object
          properties:
            action:
              type: string
              enum:
                - StartLiveData
                - StopLiveData
              description: Action to perform
            types:
              type: array
              items:
                type: string
              description: List of requested live data types
          example:
            action: StartLiveData
            types:
              - LAeq
              - LCPeak
        description: >-
          Start or stop live data.


          If you specify the `StartLiveData` action the server will start
          sending live data for the specified types.<br>

          If the server is already sending live data, the types will be updated.


          If you specify the `StopLiveData` action the server will stop sending
          live data.


          The possible live data types are:

          - Leq
            - LAeq, LCeq, LZeq, LAeqI
            - LAeqT
          - Peak
            - LAPeak, LCPeak, LZPeak
          - SPL
            - LAF, LAS, LAI
            - LCF, LCS, LCI
            - LZF, LZS, LZI
          - Statistical Levels
            -  Ln1, Ln5, Ln10, Ln50, Ln90, Ln95, Ln99
          - Moving Average
            - Examples: LAeq,5m, LAeq,60m
            - _Available values dependant on settings_
          - Octaves
            - 31.5Hz, 63Hz, 125Hz, 250Hz, 500Hz, 1KHz, 2KHz, 4KHz, 8KHz, 16KHz
          - Third Octaves
            - 6.3Hz3 to 20KHz3
            - _Names end with 3 to differentiate from octave bands_

          &nbsp;


          Some types may be unavailable depending on subscription plan.<br>

          If you specify an invalid or unavailable type, the server will ignore
          it.<br>

          If all specified types are invalid or no types are specified, the
          server will respond with an error.


          Requires an API key with the `data.live:read` scope.
      - description: >-
          The connection will timeout after 1 minute of inactivity.<br>

          To keep the connection alive, send a KeepAlive message every 30
          seconds.


          The server will respond with another KeepAlive message.
        payload:
          type: object
          properties:
            action:
              type: string
              enum:
                - KeepAlive
              description: Action to perform
          example:
            action: KeepAlive
components:
  messages:
    StartStopLiveData:
      payload:
        type: object
        properties:
          action:
            type: string
            enum:
              - StartLiveData
              - StopLiveData
            description: Action to perform
          types:
            type: array
            items:
              type: string
            description: List of requested live data types
        example:
          action: StartLiveData
          types:
            - LAeq
            - LCPeak
      description: >-
        Start or stop live data.


        If you specify the `StartLiveData` action the server will start sending
        live data for the specified types.<br>

        If the server is already sending live data, the types will be updated.


        If you specify the `StopLiveData` action the server will stop sending
        live data.


        The possible live data types are:

        - Leq
          - LAeq, LCeq, LZeq, LAeqI
          - LAeqT
        - Peak
          - LAPeak, LCPeak, LZPeak
        - SPL
          - LAF, LAS, LAI
          - LCF, LCS, LCI
          - LZF, LZS, LZI
        - Statistical Levels
          -  Ln1, Ln5, Ln10, Ln50, Ln90, Ln95, Ln99
        - Moving Average
          - Examples: LAeq,5m, LAeq,60m
          - _Available values dependant on settings_
        - Octaves
          - 31.5Hz, 63Hz, 125Hz, 250Hz, 500Hz, 1KHz, 2KHz, 4KHz, 8KHz, 16KHz
        - Third Octaves
          - 6.3Hz3 to 20KHz3
          - _Names end with 3 to differentiate from octave bands_

        &nbsp;


        Some types may be unavailable depending on subscription plan.<br>

        If you specify an invalid or unavailable type, the server will ignore
        it.<br>

        If all specified types are invalid or no types are specified, the server
        will respond with an error.


        Requires an API key with the `data.live:read` scope.
    LiveData:
      payload:
        type: object
        properties:
          type:
            type: string
            enum:
              - LiveData
            description: Type of message
          time:
            type: string
            format: date-time
            description: Time of the data
          values:
            type: array
            items:
              type: object
              properties:
                name:
                  type: string
                  description: Name of the value
                value:
                  type: number
                  description: The value in dB
            description: List of live data values
        example:
          type: LiveData
          time: '2020-01-01T00:00:00Z'
          values:
            - name: LAeq
              value: 52.3
            - name: LCPeak
              value: 63.4
    InstrumentStatus:
      payload:
        type: object
        properties:
          type:
            type: string
            enum:
              - InstrumentStatus
            description: Type of message
          time:
            type: string
            format: date-time
            description: Time of the status
          online:
            type: boolean
            description: True if the instrument is online, otherwise false
          measuring:
            type: boolean
            description: True if the instrument is measuring, otherwise false
          calibrationInProgress:
            type: boolean
            description: >-
              True if the instrument is performing a calibration, otherwise
              false
          sicInProgress:
            type: boolean
            description: >-
              True if the instrument is performing a System Integrity Check
              (SIC), otherwise false
        example:
          type: InstrumentStatus
          time: '2020-01-01T00:00:00Z'
          online: true
          measuring: true
          calibrationInProgress: false
          sicInProgress: false
    DoAction:
      payload:
        type: object
        properties:
          action:
            type: string
            enum:
              - Identify
              - Calibration
              - SIC
            description: Action to perform
        example:
          action: Identify
      description: |-
        Perform an action on the instrument.

        The possible actions are:
        - Identify
          - The instrument will flash its LED.
        - Calibration
          - The instrument will start the calibration process. You will need to attach an acoustic calibrator to the instrument.
        - SIC
          - The instrument will perform a System Integrity Check (SIC).

        &nbsp;

        Requires an API key with the `instruments:action` scope.
    ActionStatus:
      payload:
        type: object
        properties:
          type:
            type: string
            enum:
              - ActionStatus
            description: Type of message
          time:
            type: string
            format: date-time
            description: Time of the status
          action:
            type: string
            enum:
              - Identify
              - Calibration
              - SIC
            description: Action that was performed
          status:
            type: string
            enum:
              - InProgress
              - Success
              - Failed
            description: Status of the action
          error:
            oneOf:
              - type: 'null'
              - type: string
            description: May contain additional error message if status is Failed
          data:
            oneOf:
              - type: 'null'
              - title: CalibrationStatus
                type: object
                description: Status of the Calibration
                examples:
                  - time: '2020-01-01T00:00:00Z'
                    status: Success
                    level: 93.7
                    offset: 0.04
                properties:
                  time:
                    type: string
                    format: date-time
                    description: Time of the calibration
                  status:
                    type: string
                    description: Status of the calibration
                  level:
                    type: number
                    description: The calibration level in dB
                  offset:
                    type: number
                    description: The offset from factory calibration in dB
              - title: SicStatus
                type: object
                description: Status of the System Integrity Check (SIC)
                examples:
                  - time: '2020-01-01T00:00:00Z'
                    status: Success
                    _500hz: 98
                    _1khz: 98
                    _8khz: 98
                properties:
                  time:
                    type: string
                    format: date-time
                    description: Time of the SIC result
                  status:
                    type: string
                    description: Status of the SIC
                  _500Hz:
                    type: number
                    description: The 500 Hz level in dB
                  _1KHz:
                    type: number
                    description: The 1 kHz level in dB
                  _8KHz:
                    type: number
                    description: The 8 kHz level in dB
        example:
          type: ActionStatus
          time: '2020-01-01T00:00:00Z'
          action: Identify
          status: InProgress
    Error:
      payload:
        type: object
        properties:
          error:
            type: string
            description: Error code
          description:
            type: string
            description: Description of the error
        example:
          error: InvalidAction
          description: Unknown action (X)
    KeepAlive:
      description: |-
        The connection will timeout after 1 minute of inactivity.<br>
        To keep the connection alive, send a KeepAlive message every 30 seconds.

        The server will respond with another KeepAlive message.
      payload:
        type: object
        properties:
          action:
            type: string
            enum:
              - KeepAlive
            description: Action to perform
        example:
          action: KeepAlive
  schemas:
    CalibrationStatus:
      title: CalibrationStatus
      type: object
      description: Status of the Calibration
      examples:
        - time: '2020-01-01T00:00:00Z'
          status: Success
          level: 93.7
          offset: 0.04
      properties:
        time:
          type: string
          format: date-time
          description: Time of the calibration
        status:
          type: string
          description: Status of the calibration
        level:
          type: number
          description: The calibration level in dB
        offset:
          type: number
          description: The offset from factory calibration in dB
    SicStatus:
      title: SicStatus
      type: object
      description: Status of the System Integrity Check (SIC)
      examples:
        - time: '2020-01-01T00:00:00Z'
          status: Success
          _500hz: 98
          _1khz: 98
          _8khz: 98
      properties:
        time:
          type: string
          format: date-time
          description: Time of the SIC result
        status:
          type: string
          description: Status of the SIC
        _500Hz:
          type: number
          description: The 500 Hz level in dB
        _1KHz:
          type: number
          description: The 1 kHz level in dB
        _8KHz:
          type: number
          description: The 8 kHz level in dB
  securitySchemes:
    apikey:
      type: httpApiKey
      in: header
      name: X-Api-Key
      description: >-
        To access the API you must authenticate using a custom key created via
        the API console.


        The key should be passed in the X-Api-Key header.<br>

        For Example: `X-Api-Key: mycirrus-123456-AABBCCDD11223344`.


        To create a key, go to the [API
        console](https://mycirrus.cloud/developer-api) and click the "Create API
        key" button.


        When creating an API key you must choose the permissions for that key.
        These scopes control what the key can access:

        * `instruments:read` - Allows read access to instruments and related
        information

        * `instruments:write` - Allows write access to instruments and related
        information

        * `instruments:action` - Allows actions to be performed on instruments

        * `data.live:read` - Allows read access to live data

        * `data.noise:read` - Allows read access to noise data

        * `data.enviro:read` - Allows read access to environmental data
        (weather, particulates, gases, vibration)

        * `data.events:read` - Allows read access to event data

        * `data.audio:read` - Allows read access to audio data

        * `data.system:read` - Allows read access to system health data
        (calibrations, SIC, monitor stats)

        * `webhooks:read` - Allows read access to webhooks

        * `webhooks:write` - Allows write access to webhooks
  parameters:
    InstrumentSerial:
      description: The serial number of the instrument
      examples:
        - QT123456
