openapi: 3.1.0
info:
  title: MyCirrus API - Instrument info, Data and Webhooks
  version: 1.0.1
  description: API documentation for the MyCirrus API
  contact:
    name: Support
    url: https://www.cirrusresearch.com/support/
    email: support@cirrusresearch.com
  license:
    name: MIT
    identifier: MIT
  termsOfService: https://mycirrus.cloud/static/termsAndConditions.html
servers:
  - url: https://api.mycirrus.cloud/v1
    description: Production server
paths:
  /control/instruments:
    get:
      summary: Retrieve the list of instruments
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Instrument'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      operationId: getInstruments
      description: >-
        Get a list of all instruments that can be accessed with your account or
        api key.


        Requires an API key with the `instruments:read` scope.
      security:
        - apikey: []
      tags:
        - Instrument info and control
  /control/instruments/{serial}:
    put:
      summary: Set instrument information
      parameters:
        - $ref: '#/components/parameters/Instrument'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Instrument'
            examples:
              Example 1:
                value:
                  name: My Quantum
        description: Can pass the whole Instrument object or just an object containing Name
      responses:
        '204':
          description: No Content
        '400':
          $ref: '#/components/responses/OtherError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      operationId: setInstrument
      description: >-
        Change values for the specified instrument. Currently only the Name of
        the instrument can be modified.
              
        Requires an API key with the `instruments:write` scope.
      security:
        - apikey: []
      tags:
        - Instrument info and control
    get:
      summary: Get instrument information
      parameters:
        - $ref: '#/components/parameters/Instrument'
      operationId: getInstrument
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Instrument'
        '400':
          $ref: '#/components/responses/OtherError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/OtherError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      description: >-
        Get up to date information about a specific instrument. This includes
        the same values as the instrument list but only for one instrument.
              
        Requires an API key with the `instruments:read` scope.
      security:
        - apikey: []
      tags:
        - Instrument info and control
  /control/instruments/{serial}/status:
    get:
      summary: Get the status of an instrument
      parameters:
        - $ref: '#/components/parameters/Instrument'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstrumentStatus'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/OtherError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
        - apikey: []
      operationId: getInstrumentStatus
      tags:
        - Instrument info and control
      description: >-
        Get the status of an instrument. Includes flags to show if the
        instrument is online, if it is measuring and recording audio, as well as
        the calibration and SIC status.
                
        Requires an API key with the `instruments:read` scope.
  /control/instruments/{serial}/action:
    post:
      summary: Start instrument action
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  action:
                    type: string
                    enum:
                      - Identify
                      - Calibration
                      - SIC
                  status:
                    type: string
                    enum:
                      - Success
                      - Failed
                      - InProgress
              examples:
                Example 1:
                  value:
                    action: Identify
                    status: Success
        '400':
          $ref: '#/components/responses/OtherError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/OtherError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      operationId: doInstrumentAction
      description: >-
        Perform various actions on the instrument, including starting
        calibration or SIC.


        This will return the current status of the operation. *Calibration* and
        *SIC* can take a long time, so if it returns *InProgress* you will need
        to check the calibration or sic status endpoints or wait for the
        relevant webhook to fire.
                
        Requires an API key with the `instruments:action` scope.
      parameters:
        - $ref: '#/components/parameters/Instrument'
        - schema:
            type: string
            enum:
              - Identify
              - Calibration
              - SIC
          in: query
          name: action
          required: true
      tags:
        - Instrument info and control
      security:
        - apikey: []
  /control/instruments/{serial}/calibration:
    get:
      summary: Get calibration status
      parameters:
        - $ref: '#/components/parameters/Instrument'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalibrationStatus'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/OtherError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      operationId: getCalibrationStatus
      description: |-
        Get the status of the latest calibration.

        Requires an API key with the `instruments:read` scope.
      tags:
        - Instrument info and control
      security:
        - apikey: []
  /control/instruments/{serial}/sic:
    get:
      summary: Get SIC status
      parameters:
        - $ref: '#/components/parameters/Instrument'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SicStatus'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/OtherError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      operationId: GetSicStatus
      description: |-
        Get the status of the latest system integrity check.

        Requires an API key with the `instruments:read` scope.
      tags:
        - Instrument info and control
      security:
        - apikey: []
  /data/noise/measurements:
    get:
      summary: Fetch noise measurements
      parameters:
        - $ref: '#/components/parameters/Instruments'
        - $ref: '#/components/parameters/StartTime'
        - $ref: '#/components/parameters/EndTime'
        - $ref: '#/components/parameters/PeriodMeas'
        - $ref: '#/components/parameters/NoiseValues'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NoiseMeasurement'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      operationId: getMeasurements
      description: >-
        Get noise measurements for the selected instruments and time range.


        Optionally choose which values to include and what period to recalculate
        results to.


        The possible values are:

        - Leq
          - LAeq, LCeq, LZeq
          - LAE, LCE, LZE
          - LEX8
        - Peak
          - LAPeak, LCPeak, LZPeak
        - SPL Max
          - LAFMax, LASMax, LAIMax
          - LCFMax, LCSMax, LCIMax
          - LZFMax, LZSMax, LZIMax
        - Statistical Levels
          - LAF1, LAF5, LAF10, LAF50, LAF90, LAF95, LAF99
          - _Not supported if Period is used. Only available from the measurements as recorded._
        - Moving Average
          - LeqT1Max, LeqT2Max
          - _These fields will also add LeqT1Type and LeqT2Type to the results which include the friendly name of these types based on the settings._

        &nbsp;


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

        If all specified values are invalid, the server will respond with an
        error.<br>

        If no values are specified, the server will return the default results
        (LAeq, LCPeak, LAFMax).


        The maximum date range per request is 31 days. If you request a longer
        range, the server will respond with an error.<br>

        The default Period is the measurement period as configured in the
        instrument. See the settings for details.<br>

        The period can be set to anything between the measurement period and 1
        day. If you request a period outside this range, the server will respond
        with an error.


        Requires an API key with the `data.noise:read` scope.
      tags:
        - Noise data
      security:
        - apikey: []
    parameters: []
  /data/noise/timehistory:
    get:
      summary: Fetch noise time history
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TimeHistoryChannel'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      operationId: getTimeHistory
      description: >-
        Get noise time history for the selected instruments and time range.


        Optionally choose which values to include and what period to recalculate
        results to.



        The maximum date range per request is 7 days. If you request a longer
        range, the server will respond with an error.<br>

        The default Period is 1 second.<br>

        The period can be set to anything between the current time history
        setting and 1 minute. If you request a period outside this range, the
        server will respond with an error.<br>

        You can request data with a period of less than 1 second by using a
        fractional seconds value in the period. For example, `PT0.1S` for 100ms.


        Requires an API key with the `data.noise:read` scope.
      tags:
        - Noise data
      security:
        - apikey: []
      parameters:
        - $ref: '#/components/parameters/Instruments'
        - $ref: '#/components/parameters/StartTime'
        - $ref: '#/components/parameters/EndTime'
        - $ref: '#/components/parameters/PeriodTimeHist'
        - $ref: '#/components/parameters/NoiseValues'
    parameters: []
  /data/frequency/measurements:
    get:
      summary: Fetch frequency bands measurements
      parameters:
        - $ref: '#/components/parameters/Instruments'
        - $ref: '#/components/parameters/StartTime'
        - $ref: '#/components/parameters/EndTime'
        - $ref: '#/components/parameters/PeriodMeas'
        - $ref: '#/components/parameters/FreqBands'
        - $ref: '#/components/parameters/FreqWeighting'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OctaveMeasurement'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      operationId: getFrequencyMeasurements
      description: >-
        Get noise frequency band measurements for the selected instruments and
        time range.


        Optionally choose which bands and weighting to use and what period to
        recalculate results to.


        The possible options are:

        - Band
          - Octave - Includes all octave bands from 31.5Hz to 16KHz
          - Third - Includes all third octave bands from 6.3Hz to 20KHz
        - Frequency Weighting
          - A
          - C
          - Z

        &nbsp;


        If you specify an invalid or unavailable band or weighting, the server
        will respond with an error.<br>

        If no band or weighting are specified, the server will return the
        default results (Octave Z).


        The maximum date range per request is 31 days. If you request a longer
        range, the server will respond with an error.<br>

        The default Period is the measurement period as configured in the
        instrument. See the settings for details.<br>

        The period can be set to anything between the measurement period and 1
        day. If you request a period outside this range, the server will respond
        with an error.


        Requires an API key with the `data.noise:read` scope.
      tags:
        - Noise data
      security:
        - apikey: []
    parameters: []
  /data/frequency/timehistory:
    get:
      summary: Fetch frequency bands time history
      parameters:
        - $ref: '#/components/parameters/Instruments'
        - $ref: '#/components/parameters/StartTime'
        - $ref: '#/components/parameters/EndTime'
        - $ref: '#/components/parameters/PeriodTimeHist'
        - $ref: '#/components/parameters/FreqBands'
        - $ref: '#/components/parameters/FreqWeighting'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FreqTimeHistoryChannel'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      operationId: getFrequencyTimeHist
      description: >-
        Get noise frequency band time history for the selected instruments and
        time range.


        Optionally choose which bands and weighting to use and what period to
        recalculate results to.



        The maximum date range per request is 1 day. If you request a longer
        range, the server will respond with an error.<br>

        The default Period is 1 second.<br>

        The period can be set to anything between the current time history
        setting and 1 minute. If you request a period outside this range, the
        server will respond with an error.<br>

        You can request data with a period of less than 1 second by using a
        fractional seconds value in the period. For example, `PT0.1S` for 100ms.


        Requires an API key with the `data.noise:read` scope.
      tags:
        - Noise data
      security:
        - apikey: []
    parameters: []
  /data/audio:
    get:
      summary: Fetch a list of audio recordings
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AudioListItem'
          links:
            AudioItemId:
              operationId: getAudio
              description: >-
                The recording id returned in the response can be used to fetch
                the audio data.
              parameters:
                recordingId: $response.body#/id
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      operationId: getAudioList
      description: |-
        Get a list of all audio recordings for this instrumetn and time range

        Requires an API key with the `data.audio:read` scope.
      tags:
        - Noise data
      security:
        - apikey: []
      parameters:
        - $ref: '#/components/parameters/Instruments'
        - $ref: '#/components/parameters/StartTime'
        - $ref: '#/components/parameters/EndTime'
  /data/audio/{recordingId}:
    get:
      summary: Get an audio recording
      parameters:
        - schema:
            type: string
            example: xxxxxx-xxxxxx-xxxxxx
          name: recordingId
          in: path
          description: The audio recording id to retrieve
          required: true
        - schema:
            type: string
            default: FLAC
            example: FLAC
            enum:
              - FLAC
              - WAV
              - AAC
              - OGG
          in: query
          name: format
          description: Choose audio file format and codec
      responses:
        '200':
          description: OK
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
                description: The audio data encoded in the format specified in the request
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/OtherError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      operationId: getAudio
      description: |-
        Get the audio data for the given recording

        Requires an API key with the `data.audio:read` scope.
      tags:
        - Noise data
      security:
        - apikey: []
  /data/weather:
    get:
      summary: Fetch weather data
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Weather'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      operationId: getWeather
      description: >-
        Get weather measurements for the selected instruments and time range.


        Optionally choose what period to recalculate results to.


        The maximum date range per request is 31 days. If you request a longer
        range, the server will respond with an error.<br>

        The default Period is 1 minute.<br>

        The period can be set to anything between 1 minute and 1 day. If you
        request a period outside this range, the server will respond with an
        error.


        Requires an API key with the `data.enviro:read` scope.
      tags:
        - Environmental data
      security:
        - apikey: []
      parameters:
        - $ref: '#/components/parameters/Instruments'
        - $ref: '#/components/parameters/StartTime'
        - $ref: '#/components/parameters/EndTime'
        - $ref: '#/components/parameters/PeriodGeneral'
  /data/particulates:
    get:
      summary: Fetch particulate data
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Particulates'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      operationId: getParticulates
      description: >-
        Get particulates measurements for the selected instruments and time
        range.


        Optionally choose what period to recalculate results to.


        The maximum date range per request is 31 days. If you request a longer
        range, the server will respond with an error.<br>

        The default Period is 1 minute.<br>

        The period can be set to anything between 1 minute and 1 day. If you
        request a period outside this range, the server will respond with an
        error.


        Requires an API key with the `data.enviro:read` scope.
      tags:
        - Environmental data
      security:
        - apikey: []
      parameters:
        - $ref: '#/components/parameters/Instruments'
        - $ref: '#/components/parameters/StartTime'
        - $ref: '#/components/parameters/EndTime'
        - $ref: '#/components/parameters/PeriodGeneral'
  /data/gases:
    get:
      summary: Fetch gas data
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Gases'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      operationId: getGases
      description: >-
        Get gases measurements for the selected instruments and time range.


        Optionally choose what period to recalculate results to.


        The maximum date range per request is 31 days. If you request a longer
        range, the server will respond with an error.<br>

        The default Period is 1 minute.<br>

        The period can be set to anything between 1 minute and 1 day. If you
        request a period outside this range, the server will respond with an
        error.


        Requires an API key with the `data.enviro:read` scope.
      tags:
        - Environmental data
      security:
        - apikey: []
      parameters:
        - $ref: '#/components/parameters/Instruments'
        - $ref: '#/components/parameters/StartTime'
        - $ref: '#/components/parameters/EndTime'
        - $ref: '#/components/parameters/PeriodGeneral'
  /data/vibration/{type}:
    get:
      summary: Fetch vibration data
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                oneOf:
                  - description: List of PPV results
                    items:
                      $ref: '#/components/schemas/Vibration'
                  - description: List of VDV results
                    items:
                      $ref: '#/components/schemas/VibrationDose'
                type: array
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      operationId: getVibration
      tags:
        - Environmental data
      security:
        - apikey: []
      parameters:
        - schema:
            type: string
            enum:
              - PPV
              - VDV
          name: type
          in: path
          required: true
          description: The type of data to return (PPV or VDV)
        - $ref: '#/components/parameters/Instruments'
        - $ref: '#/components/parameters/StartTime'
        - $ref: '#/components/parameters/EndTime'
        - $ref: '#/components/parameters/PeriodGeneral'
      description: >-
        Get ground vibration measurements for the selected instruments and time
        range.

        Either Peak Particle Velocity (PPV) or Vibration Dose Value (VDV) based
        on the type parameter.


        Optionally choose what period to recalculate results to.


        The maximum date range per request is 31 days. If you request a longer
        range, the server will respond with an error.<br>

        The default Period is 1 minute.<br>

        The period can be set to anything between 1 minute and 1 day. If you
        request a period outside this range, the server will respond with an
        error.


        Requires an API key with the `data.enviro:read` scope.
  /data/events:
    get:
      summary: Get a list of events
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Event'
          links:
            TimeHistoryItemId:
              operationId: getEventTimeHistory
              description: >-
                The id returned in the response can be used to fetch the time
                history data.
              parameters:
                recordingId: $response.body#/timeHistoryId
            AudioItemId:
              operationId: getEventAudio
              description: >-
                The id returned in the response can be used to fetch the audio
                data.
              parameters:
                recordingId: $response.body#/audioId
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      operationId: getEvents
      description: >-
        Get a list of events for the selected instruments and time range.


        The maximum date range per request is 31 days. If you request a longer
        range, the server will respond with an error.


        Requires an API key with the `data.events:read` scope.
      tags:
        - Event data
      security:
        - apikey: []
      parameters:
        - $ref: '#/components/parameters/Instruments'
        - $ref: '#/components/parameters/StartTime'
        - $ref: '#/components/parameters/EndTime'
  /data/events/timehistory/{id}:
    get:
      summary: Get event time history
      parameters:
        - schema:
            type: string
          name: id
          in: path
          required: true
          description: ID of the time history for this event
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TimeHistoryChannel'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/OtherError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      operationId: getEventTimeHistory
      description: |-
        Get time history data for the given noise event.

        Requires an API key with the `data.events:read` scope.
      tags:
        - Event data
      security:
        - apikey: []
  /data/events/audio/{id}:
    get:
      summary: Get event audio recording
      parameters:
        - schema:
            type: string
          name: id
          in: path
          required: true
          description: ID of the audio for this event
        - schema:
            type: string
            default: FLAC
            example: FLAC
            enum:
              - FLAC
              - WAV
              - AAC
              - OGG
          in: query
          name: format
          description: Choose audio file format and codec
      responses:
        '200':
          description: OK
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
                description: The audio data encoded in the format specified in the request
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/OtherError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      description: >-
        Get the audio recording for the given noise event.


        Requires an API key with the `data.events:read` and `data.audio:read`
        scopes.
      operationId: getEventAudio
      tags:
        - Event data
      security:
        - apikey: []
  /data/calibrations:
    get:
      summary: Fetch calibration records
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Calibration'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      operationId: getCalibrations
      description: >-
        Get calibration results for the selected instruments and time range.


        The maximum date range per request is 1 year. If you request a longer
        range, the server will respond with an error.


        Requires an API key with the `data.system:read` scope.
      tags:
        - System health data
      security:
        - apikey: []
      parameters:
        - $ref: '#/components/parameters/Instruments'
        - $ref: '#/components/parameters/StartTime'
        - $ref: '#/components/parameters/EndTime'
  /data/calibrations/log:
    get:
      summary: Fetch calibration log items
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CalibrationLog'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      operationId: getCalibrationsLog
      description: >-
        Get calibration log records for the selected instruments and time range.


        The maximum date range per request is 1 year. If you request a longer
        range, the server will respond with an error.


        Requires an API key with the `data.system:read` scope.
      tags:
        - System health data
      security:
        - apikey: []
      parameters:
        - $ref: '#/components/parameters/Instruments'
        - $ref: '#/components/parameters/StartTime'
        - $ref: '#/components/parameters/EndTime'
  /data/sic:
    get:
      summary: Fetch SIC results
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SicResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      operationId: getSicResults
      description: >-
        Get System Integrity Check (SIC) results for the selected instruments
        and time range.


        The maximum date range per request is 1 year. If you request a longer
        range, the server will respond with an error.


        Requires an API key with the `data.system:read` scope.
      tags:
        - System health data
      security:
        - apikey: []
      parameters:
        - $ref: '#/components/parameters/Instruments'
        - $ref: '#/components/parameters/StartTime'
        - $ref: '#/components/parameters/EndTime'
  /data/monitor/stats:
    get:
      summary: Fetch system monitor statistics
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Monitor'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      operationId: getMonitorStats
      description: >-
        Get system monitor stats for the selected instruments and time range.


        Only supported by Quantum noise monitors.


        The maximum date range per request is 31 days. If you request a longer
        range, the server will respond with an error.


        Requires an API key with the `data.system:read` scope.
      tags:
        - System health data
      security:
        - apikey: []
      parameters:
        - $ref: '#/components/parameters/Instruments'
        - $ref: '#/components/parameters/StartTime'
        - $ref: '#/components/parameters/EndTime'
    parameters: []
  /data/monitor/events:
    get:
      summary: Fetch system monitor events
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MonitorEvent'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      operationId: getMonitorEvents
      description: >-
        Get system monitor events for the selected instruments and time range.


        Only supported by Quantum noise monitors.


        The maximum date range per request is 31 days. If you request a longer
        range, the server will respond with an error.


        Requires an API key with the `data.system:read` scope.
      tags:
        - System health data
      security:
        - apikey: []
      parameters:
        - $ref: '#/components/parameters/Instruments'
        - $ref: '#/components/parameters/StartTime'
        - $ref: '#/components/parameters/EndTime'
    parameters: []
  /data/monitor/current:
    get:
      summary: Get current system monitor stats
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MonitorCurrent'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      operationId: getMonitorCurrentStatus
      description: >-
        Get the current system monitor stats and uptime for the selected
        instruments.


        Only supported by Quantum noise monitors.


        Requires an API key with the `data.system:read` scope.
      tags:
        - System health data
      security:
        - apikey: []
      parameters:
        - $ref: '#/components/parameters/Instruments'
    parameters: []
  /webhooks:
    post:
      summary: Create a new webhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Webhook'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '400':
          $ref: '#/components/responses/OtherError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      operationId: addWebhook
      description: >-
        Add a new webhook.


        The secret can be set or left blank. If left blank, a random secret will
        be generated and returned in the response.<br>

        This is then used to sign the webhook payloads to verify that they are
        from MyCirrus.


        Requires an API key with the `webhooks:write` scope.
      tags:
        - Webhook management
      security:
        - apikey: []
    get:
      summary: Get a list of webhooks
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Webhook'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      operationId: getWebhooks
      tags:
        - Webhook management
      description: |-
        Get a list of all the current webhooks.

        Requires an API key with the `webhooks:read` scope.
      security:
        - apikey: []
  /webhooks/{webhookId}:
    delete:
      summary: Remove a webhook
      parameters:
        - name: webhookId
          in: path
          description: ID of the webhook
          required: true
          schema:
            type: string
      responses:
        '204':
          description: No Content
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/OtherError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      operationId: deleteWebhook
      description: |-
        Remove the webhook with the given id.

        Requires an API key with the `webhooks:write` scope.
      tags:
        - Webhook management
      security:
        - apikey: []
    get:
      summary: Get a webhook
      parameters:
        - name: webhookId
          in: path
          description: ID of the webhook
          required: true
          schema:
            type: string
      operationId: getWebhook
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/OtherError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      description: |-
        Get the webhook with the given id.

        Requires an API key with the `webhooks:read` scope.
      tags:
        - Webhook management
      security:
        - apikey: []
webhooks:
  NewMeasurement:
    post:
      requestBody:
        description: New Measurement avaliable
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  enum:
                    - NewMeasurement
                instrument:
                  type: string
                time:
                  type: string
                  format: date-time
                endTime:
                  type: string
                  format: date-time
                  description: End time of the most recent measurement to be stored.
      parameters:
        - $ref: '#/components/parameters/WebhookId'
        - $ref: '#/components/parameters/WebhookSignature'
      responses:
        '200':
          description: >-
            You must return a 200 OK status to indicate that the data was
            received successfully.
      tags:
        - Webhook Messages
  NewEvent:
    post:
      requestBody:
        description: New Event avaliable
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  enum:
                    - NewEvent
                instrument:
                  type: string
                time:
                  type: string
                  format: date-time
                eventTime:
                  type: string
                  format: date-time
                  description: >-
                    Start time of the most recent event to be stored. Events are
                    stored in batches so several new events may be available.
      parameters:
        - $ref: '#/components/parameters/WebhookId'
        - $ref: '#/components/parameters/WebhookSignature'
      responses:
        '200':
          description: >-
            You must return a 200 OK status to indicate that the data was
            received successfully.
      tags:
        - Webhook Messages
  InstrumentStatus:
    post:
      requestBody:
        description: Instrument is online or offline
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  enum:
                    - InstrumentStatus
                instrument:
                  type: string
                time:
                  type: string
                  format: date-time
                online:
                  type: boolean
      parameters:
        - $ref: '#/components/parameters/WebhookId'
        - $ref: '#/components/parameters/WebhookSignature'
      responses:
        '200':
          description: >-
            You must return a 200 OK status to indicate that the data was
            received successfully.
      tags:
        - Webhook Messages
  CalibrationFinished:
    post:
      requestBody:
        description: Calibration has finished
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  enum:
                    - CalibrationFinished
                instrument:
                  type: string
                time:
                  type: string
                  format: date-time
                status:
                  type: string
                  enum:
                    - Success
                    - Failed
                error:
                  type: string
                  description: May contain additional error message if status is Failed
                data:
                  $ref: '#/components/schemas/CalibrationStatus'
      parameters:
        - $ref: '#/components/parameters/WebhookId'
        - $ref: '#/components/parameters/WebhookSignature'
      responses:
        '200':
          description: >-
            You must return a 200 OK status to indicate that the data was
            received successfully.
      tags:
        - Webhook Messages
  SicFinished:
    post:
      requestBody:
        description: SIC has finished
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  enum:
                    - SicFinished
                instrument:
                  type: string
                time:
                  type: string
                  format: date-time
                status:
                  type: string
                  enum:
                    - Success
                    - Failed
                error:
                  type: string
                  description: May contain additional error message if status is Failed
                data:
                  $ref: '#/components/schemas/SicStatus'
      parameters:
        - $ref: '#/components/parameters/WebhookId'
        - $ref: '#/components/parameters/WebhookSignature'
      responses:
        '200':
          description: >-
            You must return a 200 OK status to indicate that the data was
            received successfully.
      tags:
        - Webhook Messages
components:
  securitySchemes:
    apikey:
      type: apiKey
      name: X-Api-Key
      in: header
      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
  schemas:
    Instrument:
      title: Instrument
      x-stoplight:
        id: 16nvbxvkwdq7u
      type: object
      description: Instrument details
      examples:
        - type: Noise
          serialNumber: QT123456
          model: CR:900
          name: My Quantum
          image: https://images.mycirrus.cloud/xxxxxxxx-xxxxxxxx-xxxxxxxx.jpg
          subscription:
            status: Active
            tier: Standard
          position:
            lat: 0
            long: 0
          feature:
            - SIC
            - Modem
      properties:
        type:
          type: string
          enum:
            - Noise
            - AirQuality
            - Vibration
          description: Type of instrument
        serialNumber:
          type: string
          description: Serial number of the instrument
        model:
          type: string
          description: Model of the instrument
        name:
          type: string
          description: Friendly name or description of the instrument
        image:
          type: string
          format: uri
          description: URL of the image for the instrument
        subscription:
          type: object
          properties:
            status:
              type: string
              enum:
                - Active
                - Cancelled
                - Expired
              description: Status of the subscription
            tier:
              type: string
              enum:
                - Standard
                - Pro
                - Storage
                - Track
                - Enviro
              description: Tier of the subscription
            addons:
              type: array
              items:
                type: string
                enum:
                  - Audio
              description: Addons for the subscription
          description: Subscription details for this instrument
        position:
          type: object
          properties:
            latitude:
              type: number
            longitude:
              type: number
          description: Position of the instrument
        feature:
          type: array
          items:
            type: string
            enum:
              - SIC
              - Modem
              - Weather
          description: Additional features available on this instrument
    InstrumentStatus:
      title: InstrumentStatus
      x-stoplight:
        id: k264c6yissdie
      type: object
      properties:
        online:
          type: boolean
        measuring:
          type: boolean
        calibrationInProgress:
          type: boolean
        sicInProgress:
          type: boolean
        lastCalibration:
          $ref: '#/components/schemas/CalibrationStatus'
        lastSic:
          $ref: '#/components/schemas/SicStatus'
      examples:
        - online: true
          measuring: true
          calibrationInProgress: false
          sicInProgress: false
          lastCalibration:
            time: '2020-01-01T00:00:00Z'
            status: Success
            level: 93.7
            offset: 0.04
          lastSic:
            time: '2020-01-01T00:00:00Z'
            status: Success
      description: Status of the instrument, measurement and calibration
    CalibrationStatus:
      title: CalibrationStatus
      x-stoplight:
        id: ke7hd8u47kp7w
      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
        status:
          type: string
        level:
          type: number
        offset:
          type: number
    SicStatus:
      title: SicStatus
      x-stoplight:
        id: vl2gc7q8vsoq9
      type: object
      description: Status of the System Integrity Check (SIC)
      examples:
        - time: '2020-01-01T00:00:00Z'
          status: Success
          _500hz: 98.5
          _1khz: 98.3
          _8khz: 98.4
      properties:
        time:
          type: string
          format: date-time
        status:
          type: string
        _500Hz:
          type: number
        _1KHz:
          type: number
        _8KHz:
          type: number
    Error:
      title: Error
      x-stoplight:
        id: 4q8rf56ip0wsc
      type: object
      properties:
        error:
          type: string
          description: Error code
        description:
          type: string
          description: Description of the error
    Webhook:
      title: Webhook
      x-stoplight:
        id: qizr8nxkf4o2m
      type: object
      examples:
        - id: xxxxxxxxxxxx
          type: NewMeasurement
          instrument: QT123456
          url: https://example.com/mywebhook
          secret: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
      properties:
        id:
          type: string
          description: ID of the webhook (auto-generated)
        type:
          type: string
          enum:
            - NewMeasurement
            - NewEvent
            - InstrumentStatus
            - CalibrationFinished
            - SicFinished
          description: Type of webhook
        instrument:
          type: string
          description: Serial number of the instrument
        url:
          type: string
          format: uri
          description: URL to send the webhook message to. Must use HTTPS.
        secret:
          type: string
          description: >-
            Secret used to sign the webhook message. If not set, a random secret
            will be generated.
      required:
        - type
        - instrument
        - url
    NoiseMeasurement:
      type: object
      examples:
        - startTime: '2023-06-14T23:00:00Z'
          endTime: '2023-06-14T23:15:00Z'
          duration: 900
          instrument: QT123456
          overload: false
          values:
            - name: LAeq
              value: 50.73
            - name: LCPeak
              value: 81.93
            - name: LAFMax
              value: 75.94
      title: NoiseMeasurement
      description: Noise measurement
      properties:
        startTime:
          type: string
          format: date-time
        endTime:
          type: string
          format: date-time
        duration:
          type: integer
        instrument:
          type: string
        overload:
          type: boolean
        values:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              value:
                type: number
    TimeHistoryChannel:
      title: TimeHistoryChannel
      x-stoplight:
        id: kc4nncncbyqif
      type: object
      properties:
        instrument:
          type: string
        type:
          type: string
        blocks:
          type: array
          items:
            $ref: '#/components/schemas/TimeHistoryBlock'
      description: Group of time history blocks for an instrument and type
      examples:
        - instrument: QT123456
          type: LAeq
          blocks:
            - start: '2019-08-24T14:15:00Z'
              end: '2019-08-24T14:30:00Z'
              sampleDuration: 1000
              values:
                - 55.3
                - 43.1
                - 45.6
                - ...
            - ...
    TimeHistoryBlock:
      title: TimeHistoryBlock
      x-stoplight:
        id: zhm7yzgfae7n9
      type: object
      properties:
        start:
          type: string
          format: date-time
        end:
          type: string
          format: date-time
        sampleDuration:
          type: number
        values:
          type: array
          items:
            type: number
      description: Block of time history values
      examples:
        - start: '2019-08-24T14:15:00Z'
          end: '2019-08-24T14:30:00Z'
          sampleDuration: 1000
          values:
            - 55.3
            - 43.1
            - 45.6
            - ...
    FreqTimeHistoryChannel:
      title: FreqTimeHistoryChannel
      x-stoplight:
        id: kc4nncncbyqis
      type: object
      properties:
        instrument:
          type: string
        type:
          type: string
        blocks:
          type: array
          items:
            $ref: '#/components/schemas/FreqTimeHistoryBlock'
      description: Group of frequency time history blocks for an instrument and type
      examples:
        - instrument: QT123456
          type: Octave
          blocks:
            - start: '2019-08-24T14:15:00Z'
              end: '2019-08-24T14:30:00Z'
              sampleDuration: 1000
              bands:
                - name: 31.5Hz
                  values:
                    - 55.3
                    - 43.1
                    - 45.6
                    - ...
                - ...
            - ...
    FreqTimeHistoryBlock:
      title: FreqTimeHistoryBlock
      x-stoplight:
        id: zhm7yzgfae7ns
      type: object
      properties:
        start:
          type: string
          format: date-time
        end:
          type: string
          format: date-time
        sampleDuration:
          type: number
        values:
          type: array
          items:
            type: object
            properties:
              band:
                type: string
              values:
                type: array
                items:
                  type: number
      description: Block of frequency time history bands and values
      examples:
        - start: '2019-08-24T14:15:00Z'
          end: '2019-08-24T14:30:00Z'
          sampleDuration: 1000
          values:
            - band: 31.5Hz
              values:
                - 55.3
                - 43.1
                - 45.6
                - ...
            - ...
    OctaveMeasurement:
      title: OctaveMeasurement
      x-stoplight:
        id: lte2fuxpiwymq
      type: object
      properties:
        startTime:
          type: string
          format: date-time
        endTime:
          type: string
          format: date-time
        duration:
          type: integer
        instrument:
          type: string
        overload:
          type: boolean
        values:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              value:
                type: number
      description: Octave measurement
      examples:
        - startTime: '2023-06-14T23:00:00Z'
          endTime: '2023-06-14T23:15:00Z'
          duration: 900
          instrument: QT123456
          overload: false
          values:
            - name: 31.5Hz
              value: 50.73
            - name: 63Hz
              value: 56.86
            - name: 125Hz
              value: 63.46
            - ...
    AudioListItem:
      type: object
      examples:
        - id: 3uCLgmZuV1ITGOLOBTzgDm8d9SMX52AixUtpSfEELGYsUQMmZw
          instrument: QT123456
          startTime: '2023-06-12T10:27:41'
          endTime: '2023-06-12T10:28:00'
          triggerStartTime: '2023-06-12T10:27:42Z'
          triggerEndTime: '2023-06-12T10:27:55Z'
          triggerName: Default
      properties:
        id:
          type: string
        instrument:
          type: string
        startTime:
          type: string
          format: date-time
        endTime:
          type: string
          format: date-time
        triggerStartTime:
          type: string
          format: date-time
        triggerEndTime:
          type: string
          format: date-time
        triggerName:
          type: string
    Weather:
      type: object
      examples:
        - time: '2023-06-09T01:00:00Z'
          instrument: QT123456
          windSpeed: 1.55
          windDirection: 140.37
          temperature: 10.48
          pressure: 1.012
          humidity: 82
          precipitation: 0
      properties:
        time:
          type: string
          format: date-time
          description: Time of the sample
        instrument:
          type: string
          description: Instrument serial number
        windSpeed:
          type: number
          description: Wind speed in metres per second
        windDirection:
          type: number
          description: Wind direction in degrees
        temperature:
          type: number
          description: Temperature in degrees Celsius
        pressure:
          type: number
          description: Pressure in bar
        humidity:
          type: number
          description: Relative humidity as a percentage
        precipitation:
          type: number
          description: Precipitation in millimetres per hour
    Particulates:
      type: object
      examples:
        - startTime: '2023-06-08T23:00:00Z'
          duration: 60
          instrument: SCS-BGX-000
          pM1: 3.88
          pM2p5: 4.92
          pM4p25: 5.51
          pM10: 8.95
      properties:
        startTime:
          type: string
          format: date-time
          description: Time of the sample
        duration:
          type: integer
          description: Duration of the sample in seconds
        instrument:
          type: string
          description: Instrument serial number
        pM1:
          type:
            - number
            - 'null'
          description: PM1 in micrograms per cubic metre
        pM2p5:
          type:
            - number
            - 'null'
          description: PM2.5 in micrograms per cubic metre
        pM4p25:
          type:
            - number
            - 'null'
          description: PM4.25 in micrograms per cubic metre
        pM10:
          type:
            - number
            - 'null'
          description: PM10 in micrograms per cubic metre
    Gases:
      type: object
      examples:
        - startTime: '2023-06-08T23:00:00Z'
          duration: 60
          instrument: SCS-BGX-000
          co: 207.72
          cO2: 507.06
          h2S: null
          'no': 0
          nO2: 19.12
          o3: null
          sO2: null
          voc: 493.25
      properties:
        startTime:
          type: string
          format: date-time
          description: Time of the sample
        duration:
          type: integer
          description: Duration of the sample in seconds
        instrument:
          type: string
          description: Instrument serial number
        co:
          type:
            - number
            - 'null'
          description: Carbon monoxide in parts per billion
        cO2:
          type:
            - number
            - 'null'
          description: Carbon dioxide in parts per million
        h2S:
          type:
            - number
            - 'null'
          description: Hydrogen sulphide in parts per billion
        'no':
          type:
            - number
            - 'null'
          description: Nitric oxide in parts per billion
        nO2:
          type:
            - number
            - 'null'
          description: Nitrogen dioxide in parts per billion
        o3:
          type:
            - number
            - 'null'
          description: Ozone in parts per billion
        sO2:
          type:
            - number
            - 'null'
          description: Sulphur dioxide in parts per billion
        voc:
          type:
            - number
            - 'null'
          description: Volatile organic compounds in parts per billion
    Calibration:
      type: object
      examples:
        - Time: '2022-06-07T14:45:22Z'
          Status: Success
          Instrument: QT123456
          Level: 93.7
          Offset: 0.12
      properties:
        time:
          type: string
          format: date-time
        status:
          type: string
        instrument:
          type: string
        level:
          type: number
        offset:
          type: number
    CalibrationLog:
      type: object
      examples:
        - time: '2022-06-07T11:18:42.814Z'
          user: Quantum Demo
          message: Installed and working
      properties:
        time:
          type: string
          format: date-time
        user:
          type: string
        message:
          type: string
        instrument:
          type: string
    SicResult:
      type: object
      examples:
        - time: '2023-06-14T14:00:00.2074974Z'
          instrument: QT800002
          status: Error
          _500Hz: 55.3829
          _8KHz: 35.7019
          _1KHz: 48.5379
      properties:
        time:
          type: string
          format: date-time
        instrument:
          type: string
        status:
          type: string
        _500Hz:
          type: number
        _8KHz:
          type: number
        _1KHz:
          type: number
    Monitor:
      type: object
      examples:
        - time: '2023-06-15T23:01:00Z'
          samplePeriod: 60
          cpu: 13.9
          mem: 285.8
          cache: 531.4
          temp: 36
          voltage: 11.671
          disk: 56.7
          netRx: 492
          netTx: 119
          mTot: 3793
          dTot: 24892
          lteRsrp: null
          lteRsrq: null
          lteSinr: null
          lteSignal: null
          ping: 0
          network: 10.183333333333334
          memoryPercent: 7.534932770893751
          diskPercent: 0.22778402699662545
      properties:
        time:
          type: string
          format: date-time
          description: Time of the sample
        instrument:
          type: string
          description: Instrument serial number
        samplePeriod:
          type: integer
          description: Sample period in seconds
        cpu:
          type: number
          description: CPU usage as a percentage
        mem:
          type: number
          description: Memory usage in megabytes
        cache:
          type: number
          description: Memory cache usage in megabytes
        temp:
          type: number
          description: SoC Temperature in degrees Celsius
        voltage:
          type: number
          description: Input voltage in volts
        disk:
          type: number
          description: Disk usage in megabytes
        netRx:
          type: number
          description: Network usage (receive), total in kilobits
        netTx:
          type: number
          description: Network usage (transmit), total in kilobits
        mTot:
          type: number
          description: Total memory size in megabytes
        dTot:
          type: number
          description: Total disk space in megabytes
        lteRsrp:
          type:
            - number
            - 'null'
          description: LTE signal strength
        lteRsrq:
          type:
            - number
            - 'null'
          description: LTE signal quality
        lteSinr:
          type:
            - number
            - 'null'
          description: LTE signal to noise ratio
        lteSignal:
          type:
            - number
            - 'null'
          description: LTE signal quality
        ping:
          type: number
          description: Ping time in milliseconds
        network:
          type: number
          description: Network usage, kilobits per second
        memoryPercent:
          type: number
          description: Memory usage as a percentage
        diskPercent:
          type: number
          description: Disk usage as a percentage
    MonitorCurrent:
      type: object
      examples:
        - cpu: 12.2
          mem: 8.3
          temp: 51.1
          voltage: 11.5
          disk: 0.2
          network: 3.7
          simQuota: 0
          simUsage: 0
          uptime: 900
      properties:
        instrument:
          type: string
          description: Instrument serial number
        cpu:
          type: number
          description: CPU usage as a percentage
        mem:
          type: number
          description: Memory usage as a percentage
        temp:
          type: number
          description: SoC Temperature in degrees Celsius
        voltage:
          type: number
          description: Input voltage in volts
        disk:
          type: number
          description: Disk usage as a percentage
        network:
          type: number
          description: Network usage, kilobits per second
        simQuota:
          type: number
          description: SIM card data quota in megabytes
        simUsage:
          type: number
          description: SIM card data usage in megabytes
        uptime:
          type: number
          description: Uptime in seconds
    MonitorEvent:
      type: object
      examples:
        - type: Connection
          start: '2023-06-15T07:33:09.51Z'
          end: '2023-06-15T07:34:21.524Z'
          info: Ethernet
      properties:
        type:
          type: string
          enum:
            - Connection
            - Online
            - Update
        start:
          type: string
          format: date-time
        end:
          type: string
          format: date-time
        info:
          type: string
        instrument:
          type: string
    Event:
      type: object
      examples:
        - type: Noise
          name: LAeq
          level: 65
          startTime: '2023-06-16T11:35:20Z'
          endTime: '2023-06-16T11:35:40Z'
          audioTime: '2023-06-16T11:35:25Z'
          instrument: QT123456
          overall:
            - 57.67
            - 82.53
            - 55.4
            - 60.5
            - 70.1
            - 49.93
          octave: null
          thirdOctave: null
          timeHistoryId: asliuh-fufks87s-oqkusd7
          audioId: soqufchwnw8-qkxiwtgqa5-akdicuysja
      properties:
        type:
          type: string
        name:
          type: string
        level:
          type: integer
        startTime:
          type: string
          format: date-time
        endTime:
          type: string
          format: date-time
        audioTime:
          type:
            - string
            - 'null'
          format: date-time
        instrument:
          type: string
        overall:
          type: array
          items:
            type: number
        octave:
          type: array
          items:
            type: number
        thirdOctave:
          type: array
          items:
            type: number
        timeHistoryId:
          type: string
          description: >-
            ID of the time history data for this event. Used to download the
            time history data.
        audioId:
          type: string
          description: >-
            ID of the audio data for this event. Used to download the audio
            data.
    Vibration:
      additionalProperties: false
      type: object
      examples:
        - startTime: '2023-07-07T03:19:00Z'
          duration: 60
          instrument: AABBCC
          vMaxX: 0.6442
          vMaxY: null
          vMaxZ: 0.3546
          fDomX: 5
          fDomY: null
          fDomZ: 13.5
      properties:
        startTime:
          type: string
          format: date-time
          description: Time of the sample
        duration:
          type: integer
          description: Duration of the sample in seconds
        instrument:
          type: string
          description: Instrument serial number
        vMaxX:
          type:
            - number
            - 'null'
          description: Peak particle velocity (PPV) in X direction in mm/s
        vMaxY:
          type:
            - number
            - 'null'
          description: Peak particle velocity (PPV) in Y direction in mm/s
        vMaxZ:
          type:
            - number
            - 'null'
          description: Peak particle velocity (PPV) in Z direction in mm/s
        fDomX:
          type:
            - number
            - 'null'
          description: Dominant frequency in X direction in Hz
        fDomY:
          type:
            - number
            - 'null'
          description: Dominant frequency in Y direction in Hz
        fDomZ:
          type:
            - number
            - 'null'
          description: Dominant frequency in Z direction in Hz
    VibrationDose:
      additionalProperties: false
      type: object
      examples:
        - startTime: '2023-07-06T23:00:00Z'
          duration: 60
          instrument: FODFGO
          vdvX: 0.0008
          vdvY: 0.0006
          vdvZ: 0.0022
      properties:
        startTime:
          type: string
          format: date-time
          description: Time of the sample
        duration:
          type: integer
          description: Duration of the sample in seconds
        instrument:
          type: string
          description: Instrument serial number
        vdvX:
          type: number
          description: Vibration dose value (VDV) in X direction in m/s-1.75
        vdvY:
          type: number
          description: Vibration dose value (VDV) in Y direction in m/s-1.75
        vdvZ:
          type: number
          description: Vibration dose value (VDV) in Z direction in m/s-1.75
  responses:
    OtherError:
      description: >-
        There is an error in the request, possibly missing parameter or
        incorrect url.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            Example 1:
              value:
                error: MissingParam
                description: The required parameter StartTime was missing from the request.
            Example 2:
              value:
                error: NotFound
                description: The instrument QT123456 could not be found.
    Unauthorized:
      description: Your access token is invalid or has expired
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            Example 1:
              value:
                error: TokenExpired
                description: >-
                  Your access token is invalid or has expired. Try refreshing
                  the token.
    Forbidden:
      description: You do not have permission to access this data
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            Example 1:
              value:
                error: AccessDenied
                description: You do not have permission to access this data.
    TooManyRequests:
      description: You have made too many requests in a short time
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            Example 1:
              value:
                error: TooManyRequests
                description: >-
                  You have made too many requests in a short time. Please wait
                  before trying again.
  parameters:
    Instrument:
      name: serial
      in: path
      required: true
      schema:
        type: string
        example: QT123456
      description: Serial number of the selected instrument
    StartTime:
      name: start
      in: query
      required: true
      schema:
        type: string
        format: date-time
        example: '2023-01-01T00:00:00Z'
      description: >-
        Start date and time for loading a range of data. Must be in UTC.


        This uses the ISO8601 format. For example, `2023-01-01T00:00:00Z` is 1st
        January 2023 at midnight UTC.
    EndTime:
      name: end
      in: query
      required: true
      schema:
        type: string
        format: date-time
        example: '2023-01-31T00:00:00Z'
      description: >-
        End date and time for loading a range of data. Must be in UTC.


        This uses the ISO8601 format. For example, `2023-01-01T00:00:00Z` is 1st
        January 2023 at midnight UTC.
    Instruments:
      name: instruments
      in: query
      required: true
      schema:
        type: array
        items:
          type: string
        example:
          - QT123456
          - QT234567
      description: Serial numbers of selected instruments
    NoiseValues:
      name: values
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
        default:
          - LAeq
          - LCPeak
          - LAFMax
        example:
          - LAeq
          - LCPeak
          - LAFMax
      description: Names of selected values to include in results
    PeriodGeneral:
      name: period
      in: query
      required: false
      schema:
        type: string
        format: duration
        example: PT1H
      description: >-
        Period to recalculate data samples to.


        This cannot be less than the recorded data period.


        This uses the ISO8601 duration format. For example, `P1D` is 1 day,
        `PT1H` is 1 hour, `PT1M` is 1 minute.
    PeriodMeas:
      name: period
      in: query
      required: false
      schema:
        type: string
        format: duration
        example: PT1H
      description: >-
        Period to recalculate measurement samples to.


        This cannot be less than the recorded measurement period.


        This uses the ISO8601 duration format. For example, `P1D` is 1 day,
        `PT1H` is 1 hour, `PT5M` is 5 minutes.
    PeriodTimeHist:
      name: period
      in: query
      required: false
      schema:
        type: string
        format: duration
        example: PT1H
      description: >-
        Period to recalculate time history samples to.


        This cannot be less than the recorded time history period.


        This uses the ISO8601 duration format. For example, `PT1H` is 1 hour,
        `PT1M` is 1 minute, `PT1S` is 1 second.
    FreqBands:
      name: bands
      in: query
      required: false
      schema:
        type: string
        enum:
          - Octave
          - Third
        default: Octave
        example: Octave
      description: Choose which set of frequency bands to use
    FreqWeighting:
      name: weighting
      in: query
      required: false
      schema:
        type: string
        enum:
          - A
          - C
          - Z
        default: Z
        example: Z
      description: Choose which frequency weighting to apply to the results
    WebhookId:
      name: X-Webhook-Id
      in: header
      description: The ID of the webhook that sent the request.
      schema:
        type: string
    WebhookSignature:
      name: X-Webhook-Signature
      in: header
      description: >-
        The HMAC-SHA256 signature of the request body and the secret. This can
        be used to verify the sender and content of the request.
      schema:
        type: string
tags:
  - name: Instrument info and control
    description: Endpoints for finding and controlling instruments
  - name: Noise data
    description: Endpoints for retrieving historic noise data
  - name: Environmental data
    description: Endpoints for retrieving historic environmental data
  - name: Event data
    description: Endpoints for retrieving historic event data
  - name: System health data
    description: Endpoints for retrieving historic system health data
  - name: Webhook management
    description: >-
      Webhooks allow you to receive notifications when new data is available.
      You can configure webhooks via the API itself or via the console.<br>

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


      These are the endpoints you can use to manage your webhooks:
  - name: Webhook Messages
    description: >-
      Webhooks allow you to receive notifications when new data is available.
      You can configure webhooks via the API itself or via the console.<br>

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


      When a webhook is triggered, a POST request will be sent to the URL you
      specified. The request will contain a JSON body with the data that
      triggered the webhook.


      When processing the webhook request you must return a 200 OK response to
      indicate that the data was received successfully.


      If a 200 response is not given or the request times out (5 seconds), the
      webhook will be retried up to 5 times.<br>

      To ensure a fast response we recommend you respond immediately and queue
      any further work to be done later.


      If a webhook repeatedly fails you will be notified via email. If it
      continues to fail it will then be removed.<br>

      We cannot guarantee you will get a webhook request for every event so you
      should occasionally check for new items against the normal API endpoints.

      When processing events such as new measurements its also recommended to
      request all data since you last processed it rather than just the 1 new
      measurement from the request.


      These are the types of webhook messages you can receive:
