Skip to content
API Reference/
/
Start instrument action

MyCirrus API - Instrument info, Data and Webhooks (1.0.1)

API documentation for the MyCirrus API

Download OpenAPI description
mycirrus-main.json
mycirrus-main.yaml
Overview
URL
https://www.cirrusresearch.com/support/
Support
support@cirrusresearch.com
License
MIT
Terms of Service
Languages
Servers
Mock server
https://docs.mycirrus.cloud/_mock/apis/mycirrus-main
Production server
https://api.mycirrus.cloud/v1

Instrument info and control

Endpoints for finding and controlling instruments

Operations

Retrieve the list of instruments

Request

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
curl -i -X GET \
  https://docs.mycirrus.cloud/_mock/apis/mycirrus-main/control/instruments \
  -H 'X-Api-Key: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/jsonArray [
typestring

Type of instrument

Enum"Noise""AirQuality""Vibration"
serialNumberstring

Serial number of the instrument

modelstring

Model of the instrument

namestring

Friendly name or description of the instrument

imagestring(uri)

URL of the image for the instrument

subscriptionobject

Subscription details for this instrument

positionobject

Position of the instrument

featureArray of strings

Additional features available on this instrument

Items Enum"SIC""Modem""Weather"
]
Response
application/json
[
  {
    "type": "Noise",
    "serialNumber": "QT123456",
    "model": "CR:900",
    "name": "My Quantum",
    "image": "https://images.mycirrus.cloud/xxxxxxxx-xxxxxxxx-xxxxxxxx.jpg",
    "subscription": { … },
    "position": { … },
    "feature": [ … ]
  }
]

Set instrument information

Request

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
Path
serialstringrequired

Serial number of the selected instrument

Example: QT123456
Bodyapplication/jsonrequired

Can pass the whole Instrument object or just an object containing Name

typestring

Type of instrument

Enum"Noise""AirQuality""Vibration"
serialNumberstring

Serial number of the instrument

modelstring

Model of the instrument

namestring

Friendly name or description of the instrument

imagestring(uri)

URL of the image for the instrument

subscriptionobject

Subscription details for this instrument

positionobject

Position of the instrument

featureArray of strings

Additional features available on this instrument

Items Enum"SIC""Modem""Weather"
curl -i -X PUT \
  https://docs.mycirrus.cloud/_mock/apis/mycirrus-main/control/instruments/QT123456 \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: YOUR_API_KEY_HERE' \
  -d '{
    "name": "My Quantum"
  }'

Responses

No Content

Response
No content

Get instrument information

Request

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
Path
serialstringrequired

Serial number of the selected instrument

Example: QT123456
curl -i -X GET \
  https://docs.mycirrus.cloud/_mock/apis/mycirrus-main/control/instruments/QT123456 \
  -H 'X-Api-Key: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
typestring

Type of instrument

Enum"Noise""AirQuality""Vibration"
serialNumberstring

Serial number of the instrument

modelstring

Model of the instrument

namestring

Friendly name or description of the instrument

imagestring(uri)

URL of the image for the instrument

subscriptionobject

Subscription details for this instrument

positionobject

Position of the instrument

featureArray of strings

Additional features available on this instrument

Items Enum"SIC""Modem""Weather"
Response
application/json
{
  "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"
  ]
}

Get the status of an instrument

Request

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.

Security
apikey
Path
serialstringrequired

Serial number of the selected instrument

Example: QT123456
curl -i -X GET \
  https://docs.mycirrus.cloud/_mock/apis/mycirrus-main/control/instruments/QT123456/status \
  -H 'X-Api-Key: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
onlineboolean
measuringboolean
calibrationInProgressboolean
sicInProgressboolean
lastCalibrationobject(CalibrationStatus)

Status of the Calibration

lastSicobject(SicStatus)

Status of the System Integrity Check (SIC)

Response
application/json
{
  "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"
  }
}

Start instrument action

Request

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.

Security
apikey
Path
serialstringrequired

Serial number of the selected instrument

Example: QT123456
Query
actionstringrequired
Enum"Identify""Calibration""SIC"
curl -i -X POST \
  'https://docs.mycirrus.cloud/_mock/apis/mycirrus-main/control/instruments/QT123456/action?action=Identify' \
  -H 'X-Api-Key: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
actionstring
Enum"Identify""Calibration""SIC"
statusstring
Enum"Success""Failed""InProgress"
Response
application/json
{
  "action": "Identify",
  "status": "Success"
}

Get calibration status

Request

Get the status of the latest calibration.

Requires an API key with the instruments:read scope.

Security
apikey
Path
serialstringrequired

Serial number of the selected instrument

Example: QT123456
curl -i -X GET \
  https://docs.mycirrus.cloud/_mock/apis/mycirrus-main/control/instruments/QT123456/calibration \
  -H 'X-Api-Key: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
timestring(date-time)
statusstring
levelnumber
offsetnumber
Response
application/json
{
  "time": "2020-01-01T00:00:00Z",
  "status": "Success",
  "level": 93.7,
  "offset": 0.04
}

Get SIC status

Request

Get the status of the latest system integrity check.

Requires an API key with the instruments:read scope.

Security
apikey
Path
serialstringrequired

Serial number of the selected instrument

Example: QT123456
curl -i -X GET \
  https://docs.mycirrus.cloud/_mock/apis/mycirrus-main/control/instruments/QT123456/sic \
  -H 'X-Api-Key: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
timestring(date-time)
statusstring
_500Hznumber
_1KHznumber
_8KHznumber
Response
application/json
{
  "time": "2020-01-01T00:00:00Z",
  "status": "Success",
  "_500hz": 98.5,
  "_1khz": 98.3,
  "_8khz": 98.4
}

Noise data

Endpoints for retrieving historic noise data

Operations

Environmental data

Endpoints for retrieving historic environmental data

Operations

Event data

Endpoints for retrieving historic event data

Operations

System health data

Endpoints for retrieving historic system health data

Operations

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 and click the "Create Webhook" button.

These are the endpoints you can use to manage your webhooks:

Operations

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 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:

Webhooks