# MyCirrus API - Instrument info, Data and Webhooks API documentation for the MyCirrus API Version: 1.0.1 License: MIT ## Servers Production server ``` https://api.mycirrus.cloud/v1 ``` ## Security ### apikey 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.
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 Type: apiKey In: header Name: X-Api-Key ## Download OpenAPI description [MyCirrus API - Instrument info, Data and Webhooks](https://mycirrus.redocly.app/_bundle/apis/mycirrus-main.yaml) ## Instrument info and control Endpoints for finding and controlling instruments ### Retrieve the list of instruments - [GET /control/instruments](https://mycirrus.redocly.app/apis/mycirrus-main/instrument-info-and-control/getinstruments.md): 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. ### Set instrument information - [PUT /control/instruments/{serial}](https://mycirrus.redocly.app/apis/mycirrus-main/instrument-info-and-control/setinstrument.md): 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. ### Get instrument information - [GET /control/instruments/{serial}](https://mycirrus.redocly.app/apis/mycirrus-main/instrument-info-and-control/getinstrument.md): 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. ### Get the status of an instrument - [GET /control/instruments/{serial}/status](https://mycirrus.redocly.app/apis/mycirrus-main/instrument-info-and-control/getinstrumentstatus.md): 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. ### Start instrument action - [POST /control/instruments/{serial}/action](https://mycirrus.redocly.app/apis/mycirrus-main/instrument-info-and-control/doinstrumentaction.md): 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. ### Get calibration status - [GET /control/instruments/{serial}/calibration](https://mycirrus.redocly.app/apis/mycirrus-main/instrument-info-and-control/getcalibrationstatus.md): Get the status of the latest calibration. Requires an API key with the instruments:read scope. ### Get SIC status - [GET /control/instruments/{serial}/sic](https://mycirrus.redocly.app/apis/mycirrus-main/instrument-info-and-control/getsicstatus.md): Get the status of the latest system integrity check. Requires an API key with the instruments:read scope. ## Noise data Endpoints for retrieving historic noise data ### Fetch noise measurements - [GET /data/noise/measurements](https://mycirrus.redocly.app/apis/mycirrus-main/noise-data/getmeasurements.md): 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._   If you specify an invalid or unavailable value, the server will ignore it. If all specified values are invalid, the server will respond with an error. 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. The default Period is the measurement period as configured in the instrument. See the settings for details. 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. ### Fetch noise time history - [GET /data/noise/timehistory](https://mycirrus.redocly.app/apis/mycirrus-main/noise-data/gettimehistory.md): 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. The default Period is 1 second. 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. 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. ### Fetch frequency bands measurements - [GET /data/frequency/measurements](https://mycirrus.redocly.app/apis/mycirrus-main/noise-data/getfrequencymeasurements.md): 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   If you specify an invalid or unavailable band or weighting, the server will respond with an error. 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. The default Period is the measurement period as configured in the instrument. See the settings for details. 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. ### Fetch frequency bands time history - [GET /data/frequency/timehistory](https://mycirrus.redocly.app/apis/mycirrus-main/noise-data/getfrequencytimehist.md): 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. The default Period is 1 second. 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. 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. ### Fetch a list of audio recordings - [GET /data/audio](https://mycirrus.redocly.app/apis/mycirrus-main/noise-data/getaudiolist.md): Get a list of all audio recordings for this instrumetn and time range Requires an API key with the data.audio:read scope. ### Get an audio recording - [GET /data/audio/{recordingId}](https://mycirrus.redocly.app/apis/mycirrus-main/noise-data/getaudio.md): Get the audio data for the given recording Requires an API key with the data.audio:read scope. ## Environmental data Endpoints for retrieving historic environmental data ### Fetch weather data - [GET /data/weather](https://mycirrus.redocly.app/apis/mycirrus-main/environmental-data/getweather.md): 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. The default Period is 1 minute. 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. ### Fetch particulate data - [GET /data/particulates](https://mycirrus.redocly.app/apis/mycirrus-main/environmental-data/getparticulates.md): 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. The default Period is 1 minute. 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. ### Fetch gas data - [GET /data/gases](https://mycirrus.redocly.app/apis/mycirrus-main/environmental-data/getgases.md): 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. The default Period is 1 minute. 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. ### Fetch vibration data - [GET /data/vibration/{type}](https://mycirrus.redocly.app/apis/mycirrus-main/environmental-data/getvibration.md): 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. The default Period is 1 minute. 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. ## Event data Endpoints for retrieving historic event data ### Get a list of events - [GET /data/events](https://mycirrus.redocly.app/apis/mycirrus-main/event-data/getevents.md): 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. ### Get event time history - [GET /data/events/timehistory/{id}](https://mycirrus.redocly.app/apis/mycirrus-main/event-data/geteventtimehistory.md): Get time history data for the given noise event. Requires an API key with the data.events:read scope. ### Get event audio recording - [GET /data/events/audio/{id}](https://mycirrus.redocly.app/apis/mycirrus-main/event-data/geteventaudio.md): Get the audio recording for the given noise event. Requires an API key with the data.events:read and data.audio:read scopes. ## System health data Endpoints for retrieving historic system health data ### Fetch calibration records - [GET /data/calibrations](https://mycirrus.redocly.app/apis/mycirrus-main/system-health-data/getcalibrations.md): 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. ### Fetch calibration log items - [GET /data/calibrations/log](https://mycirrus.redocly.app/apis/mycirrus-main/system-health-data/getcalibrationslog.md): 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. ### Fetch SIC results - [GET /data/sic](https://mycirrus.redocly.app/apis/mycirrus-main/system-health-data/getsicresults.md): 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. ### Fetch system monitor statistics - [GET /data/monitor/stats](https://mycirrus.redocly.app/apis/mycirrus-main/system-health-data/getmonitorstats.md): 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. ### Fetch system monitor events - [GET /data/monitor/events](https://mycirrus.redocly.app/apis/mycirrus-main/system-health-data/getmonitorevents.md): 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. ### Get current system monitor stats - [GET /data/monitor/current](https://mycirrus.redocly.app/apis/mycirrus-main/system-health-data/getmonitorcurrentstatus.md): 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. ## Webhook management Webhooks allow you to receive notifications when new data is available. You can configure webhooks via the API itself or via the console.
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: ### Create a new webhook - [POST /webhooks](https://mycirrus.redocly.app/apis/mycirrus-main/webhook-management/addwebhook.md): 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. 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. ### Get a list of webhooks - [GET /webhooks](https://mycirrus.redocly.app/apis/mycirrus-main/webhook-management/getwebhooks.md): Get a list of all the current webhooks. Requires an API key with the webhooks:read scope. ### Remove a webhook - [DELETE /webhooks/{webhookId}](https://mycirrus.redocly.app/apis/mycirrus-main/webhook-management/deletewebhook.md): Remove the webhook with the given id. Requires an API key with the webhooks:write scope. ### Get a webhook - [GET /webhooks/{webhookId}](https://mycirrus.redocly.app/apis/mycirrus-main/webhook-management/getwebhook.md): Get the webhook with the given id. Requires an API key with the webhooks:read scope. ## Webhook Messages Webhooks allow you to receive notifications when new data is available. You can configure webhooks via the API itself or via the console.
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.
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.
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: ### NewMeasurement - [POST NewMeasurement](https://mycirrus.redocly.app/apis/mycirrus-main/webhook-messages/paths/newmeasurement/post.md) ### NewEvent - [POST NewEvent](https://mycirrus.redocly.app/apis/mycirrus-main/webhook-messages/paths/newevent/post.md) ### InstrumentStatus - [POST InstrumentStatus](https://mycirrus.redocly.app/apis/mycirrus-main/webhook-messages/paths/instrumentstatus/post.md) ### CalibrationFinished - [POST CalibrationFinished](https://mycirrus.redocly.app/apis/mycirrus-main/webhook-messages/paths/calibrationfinished/post.md) ### SicFinished - [POST SicFinished](https://mycirrus.redocly.app/apis/mycirrus-main/webhook-messages/paths/sicfinished/post.md)