Sensilla GraphQL API Reference

Welcome to the Sensilla GraphQL API documentation.

Version History

Version Date Changes
1.9 2021/07/27 New section about error handling
1.8 2021/07/06 Add system events and add example repository
1.7 2021/06/08 Add more examples
1.6 2021/05/04 New documentation system, add OAQ measurements

Introduction:

About GraphQL

If you are new to GraphQL, you should take some time to familiarize yourself with some basic GraphQL concepts before digging into our documentation.

Check out the official GraphQL documentation for more information.

What is a JWT?

A JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. JWTs can be signed using a secret (with the HMAC algorithm) or a public/private key pair using RSA or ECDSA.

Although JWTs can be encrypted to also provide secrecy between parties, we will focus on signed tokens or access tokens. Signed tokens can verify the integrity of the claims contained within them, while encrypted tokens hide those claims from other parties.

When tokens are signed using public/private key pairs, the signature also certifies that only the party holding the private key is the one that signed it.

More information about JWT to be found at jwt.io

Contact

Sensilla Technologies S.A.
help@sensilla.tech

License

Sensilla Technologies S.A. - All rights reserved
https://sensilla.tech/terms-of-use/

Terms of Service: https://sensilla.tech/terms-of-use/

API Endpoints
Staging:
https://api.stg.sensilla.tech/graphql/
Production:
https://api.sensilla.tech/graphql/
Version: v1.9 (2021/07/27)
Authentication

Before you can use the Sensilla GraphQL API a valid JSON web token is required. Authentication is made using a GraphQL mutation and returns the access token required for all subsequent requests. The returned access token is valid for 24 hours and should be cached for its lifetime for performance reasons.

API usage

You are contractually bound to limit the number of API calls per 24 hours and you should never do concurrent API calls using the same user. If you require multiple API users, please get in touch with our sales team.

We reserve the right to do whatever we deem necessary in case of performance losses on excessive API querying.

Example GraphQL query (curl)

The following is an example cURL command to query GraphQL endpoints:

curl --request POST \
  --url https://<SENSILLA_API_ENDPOINT>/graphql/ \
  --header 'Authorization: Bearer eyJhbGc....' \
  --header 'Content-Type: application/json' \
  --data '{"query": "{ me { language account { id name } permissions }}}'
Structure

The data is structured in the following way:

  • Account - an account regroups multiple measurement projects
    • Group - a measurement group or measurement project brings together multiple locations
      • Location - a location is a room that has one or more sensors assigned
Valid time formats

The following lists valid time formats to query measurements or outdoor air quality measurements:

Relative
  • ms - Milliseconds
  • s - Seconds
  • m - Minutes
  • h - Hours
  • d - Days (24 hours)
  • w - Weeks (7 days)
  • n - Months (30 days)
  • y - Years (365 days)

Example to query last hour from now: 1h-ago, or last two weeks from now 2w-ago.

Absolute Unix Time

Timestamps are represented as a positive integer such as 1364410924, representing ISO 8601: 2013-03-27T19:02:04Z.
Queries using Unix timestamps can also support millisecond precision by simply appending three digits.

Absolute Formatted Time
  • yyyy/MM/dd-HH:mm:ss
  • yyyy/MM/dd HH:mm:ss
  • yyyy/MM/dd-HH:mm
  • yyyy/MM/dd HH:mm
Example repository

We have created a repository on GitHub that shows how to use the Sensilla client API in Python. The scripts include the most common functions, read time-series measurements and sending external system events used by building management systems.

Error handling

In case of a bad query or if the user has not sufficient rights an error message is thrown in the response. The HTTP status code is still a 200 OK and in the JSON response body you will find the key errors. Example error message when authentication fails:

{
  "errors": [
    {
      "message": "Unable to login with provided credentials.",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": [
        "authenticateUser"
      ]
    }
  ],
  "data": {
    "authenticateUser": null
  }
}

Example error message when querying a wrong account id:

{
  "errors": [
    {
      "message": "You do not have permission to perform this action",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": [
        "subscriptionsByAccount"
      ]
    }
  ],
  "data": {
    "subscriptionsByAccount": null
  }
}

More about error handling can be found on https://www.howtographql.com/graphql-java/7-error-handling/.

Queries

event

Gets a single event by event Id
Returns an EventType

Name Description
eventId - String If of the event

Example

Query
query event($eventId: String) {
  event(eventId: $eventId) {
    confidenceLevel
    description
    endTimestamp
    eventData
    eventType
    group {
      ...GroupTypeFragment
    }
    id
    locationIds
    metrics
    notes
    sensorIds
    startTimestamp
    state
  }
}
Variables
{
  "eventId": "12345678-1234-5678-1234-567812345678"
}
Response
{
  "data": {
    "event": {
      "confidenceLevel": 99.9,
      "description": "Window opened",
      "endTimestamp": DateTime,
      "eventData": JSONString,
      "eventType": EventEventType,
      "group": GroupType,
      "id": UUID,
      "locationIds": [123],
      "metrics": ["abc123"],
      "notes": "The window was opened in a room.",
      "sensorIds": ["xyz789"],
      "startTimestamp": DateTime,
      "state": EventState
    }
  }
}

events

Gets all events for a project
Returns [EventType]

Name Description
groupId - Int! Id of the project/group
start - DateTime! Earliest event date
end - DateTime Latest event date
locationIds - [Int] Id of the room/location to filter
sensorIds - [String] External Id of the sensor to filter
metrics - [String] Metric name to filter
eventType - String Event type to filter

Example

Query
query events($groupId: Int!, $start: DateTime!, $end: DateTime, $locationIds: [Int], $sensorIds: [String], $metrics: [String], $eventType: String) {
  events(groupId: $groupId, start: $start, end: $end, locationIds: $locationIds, sensorIds: $sensorIds, metrics: $metrics, eventType: $eventType) {
    confidenceLevel
    description
    endTimestamp
    eventData
    eventType
    group {
      ...GroupTypeFragment
    }
    id
    locationIds
    metrics
    notes
    sensorIds
    startTimestamp
    state
  }
}
Variables
{
  "groupId": 224,
  "start": 1w-ago,
  "end": now,
  "locationIds": [123],
  "sensorIds": ["xyz789"],
  "metrics": ["abc123"],
  "eventType": "xyz789"
}
Response
{
  "data": {
    "events": [
      {
        "confidenceLevel": 99.9,
        "description": "Window opened",
        "endTimestamp": DateTime,
        "eventData": JSONString,
        "eventType": EventEventType,
        "group": GroupType,
        "id": UUID,
        "locationIds": [987],
        "metrics": ["abc123"],
        "notes": "The window was opened in a room.",
        "sensorIds": ["xyz789"],
        "startTimestamp": DateTime,
        "state": EventState
      }
    ]
  }
}

group

Gets a single measurement project by id
Returns a GroupType

Name Description
id - String Id of the measurement project

Example

Query
query group($id: String) {
  group(id: $id) {
    account {
      ...AccountTypeFragment
    }
    address {
      ...GroupAddressTypeFragment
    }
    alertingchannelSet {
      ...AlertingChannelTypeFragment
    }
    alertingdetailSet {
      ...AlertingDetailTypeFragment
    }
    createdAt
    deleted
    eventSet {
      ...EventTypeFragment
    }
    externallocation {
      ...OAQLocationTypeFragment
    }
    id
    locationSet {
      ...LocationTypeFragment
    }
    name
    occupancy {
      ...GroupOccupancyTypeFragment
    }
    remotemqttbroker {
      ...RemoteMqttBrokerTypeFragment
    }
    sensorSet {
      ...SensorTypeFragment
    }
  }
}
Variables
{"id": "224"}
Response
{
  "data": {
    "group": {
      "account": AccountType,
      "address": GroupAddressType,
      "alertingchannelSet": [AlertingChannelType],
      "alertingdetailSet": [AlertingDetailType],
      "createdAt": DateTime,
      "deleted": DateTime,
      "eventSet": [EventType],
      "externallocation": OAQLocationType,
      "id": ID,
      "locationSet": [LocationType],
      "name": "Your Project Name",
      "occupancy": GroupOccupancyType,
      "remotemqttbroker": RemoteMqttBrokerType,
      "sensorSet": [SensorType]
    }
  }
}

groups

Gets a list of all measurement projects (of this user)
Returns [GroupType]

Example

Query
query groups {
  groups {
    account {
      ...AccountTypeFragment
    }
    address {
      ...GroupAddressTypeFragment
    }
    alertingchannelSet {
      ...AlertingChannelTypeFragment
    }
    alertingdetailSet {
      ...AlertingDetailTypeFragment
    }
    createdAt
    deleted
    eventSet {
      ...EventTypeFragment
    }
    externallocation {
      ...OAQLocationTypeFragment
    }
    id
    locationSet {
      ...LocationTypeFragment
    }
    name
    occupancy {
      ...GroupOccupancyTypeFragment
    }
    remotemqttbroker {
      ...RemoteMqttBrokerTypeFragment
    }
    sensorSet {
      ...SensorTypeFragment
    }
  }
}
Response
{
  "data": {
    "groups": [
      {
        "account": AccountType,
        "address": GroupAddressType,
        "alertingchannelSet": [AlertingChannelType],
        "alertingdetailSet": [AlertingDetailType],
        "createdAt": DateTime,
        "deleted": DateTime,
        "eventSet": [EventType],
        "externallocation": OAQLocationType,
        "id": ID,
        "locationSet": [LocationType],
        "name": "Your Project Name",
        "occupancy": GroupOccupancyType,
        "remotemqttbroker": RemoteMqttBrokerType,
        "sensorSet": [SensorType]
      }
    ]
  }
}

location

Gets a single room by Id
Returns a LocationType

Name Description
id - String Id of the room

Example

Query
query location($id: String) {
  location(id: $id) {
    account {
      ...AccountTypeFragment
    }
    createdAt
    deleted
    group {
      ...GroupTypeFragment
    }
    hasActiveMonitoringMeasurement
    id
    lastMeasurement
    name
    sensorSet {
      ...SensorTypeFragment
    }
    user {
      ...UserTypeFragment
    }
  }
}
Variables
{"id": "320"}
Response
{
  "data": {
    "location": {
      "account": AccountType,
      "createdAt": DateTime,
      "deleted": DateTime,
      "group": GroupType,
      "hasActiveMonitoringMeasurement": true,
      "id": ID,
      "lastMeasurement": DateTime,
      "name": "Room 123",
      "sensorSet": [SensorType],
      "user": UserType
    }
  }
}

locations

Gets a list of all rooms in the measurement project
Returns [LocationType]

Example

Query
query locations {
  locations {
    account {
      ...AccountTypeFragment
    }
    createdAt
    deleted
    group {
      ...GroupTypeFragment
    }
    hasActiveMonitoringMeasurement
    id
    lastMeasurement
    locations {
      account {
        ...AccountTypeFragment
      }
      createdAt
      group {
        ...GroupTypeFragment
      }
      id
      locations {
        account {
          ...AccountTypeFragment
        }
        createdAt
        deleted
        group {
          ...GroupTypeFragment
        }
        hasActiveMonitoringMeasurement
        id
        lastMeasurement
        locations {
          ...RecursiveMonitoringMeasurementTypeFragment
        }
        name
        sensorSet {
          ...SensorTypeFragment
        }
        user {
          ...UserTypeFragment
        }
      }
      user {
        ...UserTypeFragment
      }
    }
    name
    sensorSet {
      ...SensorTypeFragment
    }
    user {
      ...UserTypeFragment
    }
  }
}
Response
{
  "data": {
    "locations": [
      {
        "account": AccountType,
        "createdAt": DateTime,
        "deleted": DateTime,
        "group": GroupType,
        "hasActiveMonitoringMeasurement": true,
        "id": ID,
        "lastMeasurement": DateTime,
        "locations": [MonitoringMeasurementType],
        "name": "Room 123",
        "sensorSet": [SensorType],
        "user": UserType
      }
    ]
  }
}

me

Gets information about the current user
Returns a UserType

Example

Query
query me {
  me {
    account {
      ...AccountTypeFragment
    }
    firstName
    language
    lastName
  }
}
Response
{
  "data": {
    "me": {
      "account": AccountType,
      "firstName": "John",
      "language": "en",
      "lastName": "Doe"
    }
  }
}

measurements

Gets a list of measurements of a room
Returns [MeasurementType]

Name Description
location - Int Id of the room
start - String Earliest measurement date. Default = "1d-ago"
end - String Latest measurement date. Default = "now"

Example

Query
query measurements($location: Int, $start: String, $end: String) {
  measurements(location: $location, start: $start, end: $end) {
    airPressure
    calibratedTvocMgM3
    calibratedTvocPpb
    co2Concentration
    environmentalRelativeHumidity
    environmentalTemperature
    massConcentrationPm10
    massConcentrationPm100
    massConcentrationPm25
    massConcentrationPm40
    numberConcentrationPm10
    numberConcentrationPm100
    numberConcentrationPm25
    numberConcentrationPm40
    numberConcentrationPm5
    timestamp
    typicalParticleSize
  }
}
Variables
{
  "location": 82,
  "start": "1w-ago",
  "end": "now"
}
Response
{
  "data": {
    "measurements": [
      {
        "airPressure": 97086,
        "calibratedTvocMgM3": 1.109766721725464,
        "calibratedTvocPpb": 246.8718566894531,
        "co2Concentration": 539.0067749023438,
        "environmentalRelativeHumidity": 39.60165214538574,
        "environmentalTemperature": 23.641700744628906,
        "massConcentrationPm10": 0.6494534015655518,
        "massConcentrationPm100": 0.6579645872116089,
        "massConcentrationPm25": 0.6572332382202148,
        "massConcentrationPm40": 0.6579635739326477,
        "numberConcentrationPm10": 5.533976078033447,
        "numberConcentrationPm100": 5.546431541442871,
        "numberConcentrationPm25": 5.545812606811523,
        "numberConcentrationPm40": 5.546197891235352,
        "numberConcentrationPm5": 4.880741119384766,
        "timestamp": 1617616800,
        "typicalParticleSize": 0.5192219018936157
      }
    ]
  }
}

measurementsBySensor

Gets a list of measurements of a sensor
Returns [MeasurementType]

Name Description
sensorId - String! Id of the sensor
location - Int Optional Id of the room
start - String Earliest measurement date. Default = "1d-ago"
end - String Latest measurement date. Default = "now"

Example

Query
query measurementsBySensor($sensorId: String!, $location: Int, $start: String, $end: String) {
  measurementsBySensor(sensorId: $sensorId, location: $location, start: $start, end: $end) {
    airPressure
    calibratedTvocMgM3
    calibratedTvocPpb
    co2Concentration
    environmentalRelativeHumidity
    environmentalTemperature
    massConcentrationPm10
    massConcentrationPm100
    massConcentrationPm25
    massConcentrationPm40
    numberConcentrationPm10
    numberConcentrationPm100
    numberConcentrationPm25
    numberConcentrationPm40
    numberConcentrationPm5
    timestamp
    typicalParticleSize
  }
}
Variables
{
  "sensorId": "device-xxxxxxxxxxxx",
  "location": 82,
  "start": "1w-ago",
  "end": "now"
}
Response
{
  "data": {
    "measurementsBySensor": [
      {
        "airPressure": 97086,
        "calibratedTvocMgM3": 1.109766721725464,
        "calibratedTvocPpb": 246.8718566894531,
        "co2Concentration": 539.0067749023438,
        "environmentalRelativeHumidity": 39.60165214538574,
        "environmentalTemperature": 23.641700744628906,
        "massConcentrationPm10": 0.6494534015655518,
        "massConcentrationPm100": 0.6579645872116089,
        "massConcentrationPm25": 0.6572332382202148,
        "massConcentrationPm40": 0.6579635739326477,
        "numberConcentrationPm10": 5.533976078033447,
        "numberConcentrationPm100": 5.546431541442871,
        "numberConcentrationPm25": 5.545812606811523,
        "numberConcentrationPm40": 5.546197891235352,
        "numberConcentrationPm5": 4.880741119384766,
        "timestamp": 1617616800,
        "typicalParticleSize": 0.5192219018936157
      }
    ]
  }
}

oaqMeasurements

Gets a list of measurements of outdoor air quality location
Returns [OAQMeasurementType]

Name Description
groupId - Int Id of the project/group
start - String Earliest measurement date. Default = "1d-ago"
end - String Latest measurement date. Default = "now"

Example

Query
query oaqMeasurements($groupId: Int, $start: String, $end: String) {
  oaqMeasurements(groupId: $groupId, start: $start, end: $end) {
    co
    no2
    o3
    pm10
    pm25
    so2
    timestamp
  }
}
Variables
{
  "groupId": 224,
  "start": "1w-ago",
  "end": "now"
}
Response
{
  "data": {
    "oaqMeasurements": [
      {
        "co": 140,
        "no2": 8.399999618530273,
        "o3": 73,
        "pm10": 15,
        "pm25": 4,
        "so2": 4.400000095367432,
        "timestamp": 1617616800
      }
    ]
  }
}

roomTypesList

Gets a list of all possible room types
Returns a String

Example

Query
query roomTypesList {
  roomTypesList
}
Response
{"data": {"roomTypesList": "xyz789"}}

sensor

Gets a single sensor by id
Returns a SensorType

Name Description
externalId - String Id of the sensor

Example

Query
query sensor($externalId: String) {
  sensor(externalId: $externalId) {
    account {
      ...AccountTypeFragment
    }
    batteryCharge
    createdAt
    externalId
    firmwareVersion
    floorplanPosition {
      ...FloorplanPositionTypeFragment
    }
    group {
      ...GroupTypeFragment
    }
    hasActiveMonitoring
    id
    isReporting
    lastMeasurement
    lastOnline
    location {
      ...LocationTypeFragment
    }
    name
    positionDescription
  }
}
Variables
{
  "externalId": "device-xxxxxxxxxxxx"
}
Response
{
  "data": {
    "sensor": {
      "account": AccountType,
      "batteryCharge": 33,
      "createdAt": DateTime,
      "externalId": "device-xxxxxxxxxxxx",
      "firmwareVersion": 3061,
      "floorplanPosition": FloorplanPositionType,
      "group": GroupType,
      "hasActiveMonitoring": false,
      "id": ID,
      "isReporting": true,
      "lastMeasurement": DateTime,
      "lastOnline": DateTime,
      "location": LocationType,
      "name": "Sensor xzy",
      "positionDescription": "North wall"
    }
  }
}

sensors

Gets a list of sensors of a measurement project
Returns [SensorType]

Name Description
groupId - String Id of the measurement project

Example

Query
query sensors($groupId: String) {
  sensors(groupId: $groupId) {
    account {
      ...AccountTypeFragment
    }
    batteryCharge
    createdAt
    externalId
    firmwareVersion
    floorplanPosition {
      ...FloorplanPositionTypeFragment
    }
    group {
      ...GroupTypeFragment
    }
    hasActiveMonitoring
    id
    isReporting
    lastMeasurement
    lastOnline
    location {
      ...LocationTypeFragment
    }
    name
    positionDescription
    sensors {
      account {
        ...AccountTypeFragment
      }
      createdAt
      group {
        ...GroupTypeFragment
      }
      id
      location {
        ...LocationTypeFragment
      }
      sensors {
        account {
          ...AccountTypeFragment
        }
        batteryCharge
        createdAt
        externalId
        firmwareVersion
        floorplanPosition {
          ...FloorplanPositionTypeFragment
        }
        group {
          ...GroupTypeFragment
        }
        hasActiveMonitoring
        id
        isReporting
        lastMeasurement
        lastOnline
        location {
          ...LocationTypeFragment
        }
        name
        positionDescription
        sensors {
          ...RecursiveMonitoringMeasurementTypeFragment
        }
      }
    }
  }
}
Variables
{"groupId": 224}
Response
{
  "data": {
    "sensors": [
      {
        "account": AccountType,
        "batteryCharge": 33,
        "createdAt": DateTime,
        "externalId": "device-xxxxxxxxxxxx",
        "firmwareVersion": 3061,
        "floorplanPosition": FloorplanPositionType,
        "group": GroupType,
        "hasActiveMonitoring": true,
        "id": ID,
        "isReporting": true,
        "lastMeasurement": DateTime,
        "lastOnline": DateTime,
        "location": LocationType,
        "name": "Sensor xzy",
        "positionDescription": "North wall",
        "sensors": [MonitoringMeasurementType]
      }
    ]
  }
}

status

Get the health status of the system
Returns a Status

Example

Query
query status {
  status {
    databaseEngine
    storageEngine
  }
}
Response
{
  "data": {
    "status": {
      "databaseEngine": "OK",
      "storageEngine": "OK"
    }
  }
}

Mutations

addSystemEvent

Create a new external system event
Returns an AddSystemEvent

Name Description
description - String! Annotation text
end - Int Event end timestamp (UTC)
eventData - String Raw JSON event data
groupId - Int! Project id for the new annotation
locationIds - [Int] Location id's for the new annotation
metrics - [String] Metric names for the new annotation
notes - String Annotation additional content
sensorIds - [String] Sensor id's for the new annotation
start - Int! Event start timestamp (UTC)

Example

Query
mutation addSystemEvent($description: String!, $end: Int, $eventData: String, $groupId: Int!, $locationIds: [Int], $metrics: [String], $notes: String, $sensorIds: [String], $start: Int!) {
  addSystemEvent(description: $description, end: $end, eventData: $eventData, groupId: $groupId, locationIds: $locationIds, metrics: $metrics, notes: $notes, sensorIds: $sensorIds, start: $start) {
    event {
      ...EventTypeFragment
    }
  }
}
Variables
{
  "description": "abc123",
  "end": 123,
  "eventData": "abc123",
  "groupId": 987,
  "locationIds": [123],
  "metrics": ["abc123"],
  "notes": "abc123",
  "sensorIds": ["xyz789"],
  "start": 987
}
Response
{"data": {"addSystemEvent": {"event": EventType}}}

authenticateUser

Generate JWT for user
Returns an AuthenticateUser

Name Description
password - String! Your API password
username - String! Your API username

Example

Query
mutation authenticateUser($password: String!, $username: String!) {
  authenticateUser(password: $password, username: $username) {
    bearerToken
    expiresIn
  }
}
Variables
{
  "password": "<your_secure_passphrase>",
  "username": "john.doe@example.com"
}
Response
{
  "data": {
    "authenticateUser": {
      "bearerToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Ik...",
      "expiresIn": 86400
    }
  }
}

updateSystemEvent

Update the end timestamp of a external system event
Returns an UpdateSystemEvent

Name Description
end - Int Event end timestamp (UTC)
eventId - String Id of the event (UUID4)

Example

Query
mutation updateSystemEvent($end: Int, $eventId: String) {
  updateSystemEvent(end: $end, eventId: $eventId) {
    event {
      ...EventTypeFragment
    }
  }
}
Variables
{
  "end": 987,
  "eventId": "12345678-1234-5678-1234-567812345678"
}
Response
{"data": {"updateSystemEvent": {"event": EventType}}}

Types

AccountType

Represents an account.

Field Name Description
createdAt - DateTime!
id - ID!
name - String
Example
{
  "createdAt": DateTime,
  "id": ID,
  "name": "Your Company Name"
}

AddSystemEvent

Create a new external system event.

Field Name Description
event - EventType
Example
{"event": EventType}

AuthenticateUser

Generate JWT for user

Field Name Description
bearerToken - String JSON Web Token
expiresIn - Int Access token lifetime (in seconds)
Example
{
  "bearerToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Ik...",
  "expiresIn": 86400
}

Boolean

The Boolean scalar type represents true or false.

Example
true

DateTime

The DateTime scalar type represents a DateTime value as specified by iso8601.

Example
object

EventType

Represents an event.

Field Name Description
confidenceLevel - Float
description - String!
endTimestamp - DateTime
eventData - JSONString
eventType - EventEventType!
group - GroupType
id - UUID!
locationIds - [Int!]!
metrics - [String!]!
notes - String
sensorIds - [String!]!
startTimestamp - DateTime!
state - EventState!
Example
{
  "confidenceLevel": 99.9,
  "description": "Window opened",
  "endTimestamp": DateTime,
  "eventData": JSONString,
  "eventType": EventEventType,
  "group": GroupType,
  "id": UUID,
  "locationIds": [987],
  "metrics": ["abc123"],
  "notes": "The window was opened in a room.",
  "sensorIds": ["xyz789"],
  "startTimestamp": DateTime,
  "state": EventState
}

Float

The Float scalar type represents signed double-precision fractional values as specified by IEEE 754.

Example
987.65

GroupAddressType

Represents an address for a measurement project.

Field Name Description
building - String
city - String
country - String
floor - String
googlePlusCode - String
latitude - Float
longitude - Float
state - String
street - String
zip - String
Example
{
  "building": "Headquarter",
  "city": "Howald",
  "country": "Luxembourg",
  "floor": "Ground Floor",
  "googlePlusCode": "H4GQ+WC Hesperange",
  "latitude": 49.577421,
  "longitude": 6.138567,
  "state": ,
  "street": "1 rue Peternelchen",
  "zip": 2370
}

GroupType

Represents a measurement project.

Field Name Description
account - AccountType
address - GroupAddressType
alertingchannelSet - [AlertingChannelType!]!
alertingdetailSet - [AlertingDetailType!]!
createdAt - DateTime!
deleted - DateTime
eventSet - [EventType!]!
externallocation - OAQLocationType
id - ID!
locationSet - [LocationType!]!
name - String
occupancy - GroupOccupancyType
remotemqttbroker - RemoteMqttBrokerType
sensorSet - [SensorType!]!
Example
{
  "account": AccountType,
  "address": GroupAddressType,
  "alertingchannelSet": [AlertingChannelType],
  "alertingdetailSet": [AlertingDetailType],
  "createdAt": DateTime,
  "deleted": DateTime,
  "eventSet": [EventType],
  "externallocation": OAQLocationType,
  "id": ID,
  "locationSet": [LocationType],
  "name": "Your Project Name",
  "occupancy": GroupOccupancyType,
  "remotemqttbroker": RemoteMqttBrokerType,
  "sensorSet": [SensorType]
}

ID

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as "4") or integer (such as 4) input value will be accepted as an ID.

Example
object

Int

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Example
987

LocationType

Represents a room.

Field Name Description
account - AccountType
createdAt - DateTime!
deleted - DateTime
group - GroupType
hasActiveMonitoringMeasurement - Boolean
id - ID!
lastMeasurement - DateTime
name - String
sensorSet - [SensorType!]!
user - UserType
Example
{
  "account": AccountType,
  "createdAt": DateTime,
  "deleted": DateTime,
  "group": GroupType,
  "hasActiveMonitoringMeasurement": false,
  "id": ID,
  "lastMeasurement": DateTime,
  "name": "Room 123",
  "sensorSet": [SensorType],
  "user": UserType
}

MeasurementType

Represents a measurement from a Sensilla IAQ device.

Field Name Description
airPressure - Float calibrated atmospheric pressure (Pa)
calibratedTvocMgM3 - Float calibrated TVOC in mg/m3(converted from calibrated_tvoc_ppb, using average molecular mass)
calibratedTvocPpb - Float calibrated TVOC (ppb)
co2Concentration - Float calibrated CO2concentration (ppm)
environmentalRelativeHumidity - Float calibrated relative humidity (%)
environmentalTemperature - Float calibrated temperature (°C)
massConcentrationPm10 - Float PM1.0 mass concentration of particles with an aerodynamic diameter between 1µm and 0.3µm (µg/m3)
massConcentrationPm100 - Float PM10 mass concentration of particles with an aerodynamic diameter between 10µm and 0.3µm (µg/m3)
massConcentrationPm25 - Float PM2.5 mass concentration of particles with an aerodynamic diameter between 2.5µm and 0.3µm (µg/m3)
massConcentrationPm40 - Float PM4 mass concentration of particles with an aerodynamic diameter between 4µm and 0.3µm (µg/m3)
numberConcentrationPm10 - Float PM1.0 number of particles with an aerodynamic diameter between 1µm and 0.3µm per cubic meter (1/m³)
numberConcentrationPm100 - Float PM10 number of particles with an aerodynamic diameter between 10µm and 0.3µm per cubic meter (1/m³)
numberConcentrationPm25 - Float PM2.5 number of particles with an aerodynamic diameter between 2.5µm and 0.3µm per cubic meter (1/m³)
numberConcentrationPm40 - Float PM4 number of particles with an aerodynamic diameter between 4µm and 0.3µm per cubic meter (1/m³)
numberConcentrationPm5 - Float PM0.5 number of particles with an aerodynamic diameter between 0.5µm and 0.3µm per cubic meter (1/m³)
timestamp - Int! Unix timestamp (UTC)
typicalParticleSize - Float average particle size (µm)
Example
{
  "airPressure": 97086,
  "calibratedTvocMgM3": 1.109766721725464,
  "calibratedTvocPpb": 246.8718566894531,
  "co2Concentration": 539.0067749023438,
  "environmentalRelativeHumidity": 39.60165214538574,
  "environmentalTemperature": 23.641700744628906,
  "massConcentrationPm10": 0.6494534015655518,
  "massConcentrationPm100": 0.6579645872116089,
  "massConcentrationPm25": 0.6572332382202148,
  "massConcentrationPm40": 0.6579635739326477,
  "numberConcentrationPm10": 5.533976078033447,
  "numberConcentrationPm100": 5.546431541442871,
  "numberConcentrationPm25": 5.545812606811523,
  "numberConcentrationPm40": 5.546197891235352,
  "numberConcentrationPm5": 4.880741119384766,
  "timestamp": 1617616800,
  "typicalParticleSize": 0.5192219018936157
}

OAQMeasurementType

Represents an OAQ measurement. The listed values are not available on all outdoor air quality stations and may return null values.

Field Name Description
co - Float Carbon Monoxide mass concentration (µg/m³)
no2 - Float Nitrogen Dioxide mass concentration (µg/m³)
o3 - Float Ozone mass concentration (µg/m³)
pm10 - Float Particulate matter less than 10 micrometers in diameter mass concentration (µg/m³)
pm25 - Float Particulate matter less than 2.5 micrometers in diameter mass concentration (µg/m³)
so2 - Float Sulfur Dioxide mass concentration (µg/m³)
timestamp - Int! Unix timestamp (UTC)
Example
{
  "co": 140,
  "no2": 8.399999618530273,
  "o3": 73,
  "pm10": 15,
  "pm25": 4,
  "so2": 4.400000095367432,
  "timestamp": 1617616800
}

SensorType

Represents a sensor.

Field Name Description
account - AccountType
batteryCharge - Int
createdAt - DateTime!
externalId - String!
firmwareVersion - Int
floorplanPosition - FloorplanPositionType
group - GroupType
hasActiveMonitoring - Boolean
id - ID!
isReporting - Boolean
lastMeasurement - DateTime
lastOnline - DateTime
location - LocationType
name - String
positionDescription - String
Example
{
  "account": AccountType,
  "batteryCharge": 33,
  "createdAt": DateTime,
  "externalId": "device-xxxxxxxxxxxx",
  "firmwareVersion": 3061,
  "floorplanPosition": FloorplanPositionType,
  "group": GroupType,
  "hasActiveMonitoring": false,
  "id": ID,
  "isReporting": false,
  "lastMeasurement": DateTime,
  "lastOnline": DateTime,
  "location": LocationType,
  "name": "Sensor xzy",
  "positionDescription": "North wall"
}

Status

Example health status.

Field Name Description
databaseEngine - String
storageEngine - String
Example
{
  "databaseEngine": "OK",
  "storageEngine": "OK"
}

String

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

UpdateSystemEvent

Update the end timestamp of a external system event.

Field Name Description
event - EventType
Example
{"event": EventType}

UserType

Represents an authenticated user.

Field Name Description
account - AccountType
firstName - String!
language - String
lastName - String!
Example
{
  "account": AccountType,
  "firstName": "John",
  "language": "en",
  "lastName": "Doe"
}