BIOTCloud GraphQL API Reference

Getting started

This page contains documentation for BIOTCloud API.
Our API is built using GraphQL and can be used to retrieve objects and data from the system.
The main idea of GraphQL is that you request only for those object attributes that you need.
All main API functions can be found in Query and Mutation sections. In the Query section you can find all available getters for the system.
In Mutation section you can find API calls that will mutate (modify) the system in some way.

All GraphQL API calls must be executed under a single address: https://queryapi.perf.biotcloud.com/api/v1/graphql
Please check Authorization section for details how to authorize.

Authorization

BIOTCloud API is protected with Authorization token. To make API calls you need a token that will give you access to your IOT devices. Please contact BIOT if you don't have access to your token yet.

Token must be provided as a separate authorization header to HTTP call: authorization: 'Bearer YOUR_TOKEN'

Queries

`getCommandStatus`

Description

Get commands status. An example of command is light override - see mutation section.

Response

Returns a Command

Arguments

Name	Description
`id` - `Int!`	An identification of a command - id.

Example

Query

query GetCommandStatus($id: Int!) {
  getCommandStatus(id: $id) {
    id
    type
    data
    response
    sent
    confirmed
    timeout
  }
}

Variables

{"id": 987}

Response

{
  "data": {
    "getCommandStatus": {
      "id": "abc123",
      "type": "xyz789",
      "data": {},
      "response": {},
      "sent": "2007-12-03T10:15:30Z",
      "confirmed": "2007-12-03T10:15:30Z",
      "timeout": "2007-12-03T10:15:30Z"
    }
  }
}

Queries

`getDevice`

Description

Get device by uid.

Response

Returns a Device

Arguments

Name	Description
`uid` - `String!`	An identification of device - uid. It's required.

Example

Query

query GetDevice($uid: String!) {
  getDevice(uid: $uid) {
    id
    uid
    type
    slot {
      id
      poi {
        ...PoiFragment
      }
      device {
        ...DeviceFragment
      }
      parentId
      children {
        ...SlotFragment
      }
      parentSlot {
        ...SlotFragment
      }
      geometry {
        ...GeoJsonFragment
      }
    }
    createdAt
    groups {
      id
      name
      schedules {
        ...ScheduleFragment
      }
    }
    needsAttentionAlerts {
      severity
      type
      active
      id
      confirmedBy
      tags
      createdAt
      startedAt
      stoppedAt
      confirmedAt
    }
    lightComponents {
      id
      schedules {
        ...ScheduleFragment
      }
      lastValue
    }
    meterComponents {
      id
      lastValue
      type
    }
    cameraComponents {
      id
      lastValue
    }
    motionSensors {
      id
      type
      lastValue
    }
    lightSensorComponents {
      id
      lastValue
    }
  }
}

Variables

{"uid": "xyz789"}

Response

{
  "data": {
    "getDevice": {
      "id": 4,
      "uid": "xyz789",
      "type": "xyz789",
      "slot": Slot,
      "createdAt": "2007-12-03T10:15:30Z",
      "groups": [Group],
      "needsAttentionAlerts": [Alert],
      "lightComponents": [LightComponent],
      "meterComponents": [MeterComponent],
      "cameraComponents": [CameraComponent],
      "motionSensors": [MotionSensor],
      "lightSensorComponents": [LightSensorComponent]
    }
  }
}

Queries

`getDeviceAlerts`

Description

Collection of device alerts

Response

Returns an AlertsCollection

Arguments

Name	Description
`skip` - `Int`	Skip and limit are useful for pagination. If not defined the default value (0) will be set. It's like a cursor to return records from range ( skip * limit, ( skip * limit ) + limit ). Default = `0`
`limit` - `Int`	Skip and limit are useful for pagination. If not defined the default value (100) will be set. It's like a cursor to return records from range ( skip * limit, ( skip * limit ) + limit ). Default = `100`
`filter` - `AlertsFilter`	An additional filters i.e. date range, confirmation status, show only active/inactive alerts. These filters are optional
`deviceUid` - `String!`	device uid - an identification of device

Example

Query

query GetDeviceAlerts(
  $skip: Int,
  $limit: Int,
  $filter: AlertsFilter,
  $deviceUid: String!
) {
  getDeviceAlerts(
    skip: $skip,
    limit: $limit,
    filter: $filter,
    deviceUid: $deviceUid
  ) {
    alerts {
      severity
      type
      active
      id
      confirmedBy
      tags
      createdAt
      startedAt
      stoppedAt
      confirmedAt
    }
    count
  }
}

Variables

{
  "skip": 0,
  "limit": 100,
  "filter": AlertsFilter,
  "deviceUid": "xyz789"
}

Response

{
  "data": {
    "getDeviceAlerts": {"alerts": [Alert], "count": 987}
  }
}

Queries

`getDevices`

Description

Get list of devices.

Response

Returns a Devices!

Arguments

Name	Description
`skip` - `Int`	Skip and limit are useful for pagination. If not defined the default value (0) will be set. It's like a cursor to return records from range ( skip * limit, ( skip * limit ) + limit ). Default = `0`
`limit` - `Int`	Skip and limit are useful for pagination. If not defined the default value (100) will be set. It's like a cursor to return records from range ( skip * limit, ( skip * limit ) + limit ). Default = `100`
`type` - `String`	Filter device type. Parameter is optional. Default = `""`

Example

Query

query GetDevices(
  $skip: Int,
  $limit: Int,
  $type: String
) {
  getDevices(
    skip: $skip,
    limit: $limit,
    type: $type
  ) {
    devices {
      id
      uid
      type
      slot {
        ...SlotFragment
      }
      createdAt
      groups {
        ...GroupFragment
      }
      needsAttentionAlerts {
        ...AlertFragment
      }
      lightComponents {
        ...LightComponentFragment
      }
      meterComponents {
        ...MeterComponentFragment
      }
      cameraComponents {
        ...CameraComponentFragment
      }
      motionSensors {
        ...MotionSensorFragment
      }
      lightSensorComponents {
        ...LightSensorComponentFragment
      }
    }
    count
  }
}

Variables

{"skip": 0, "limit": 100, "type": ""}

Response

{
  "data": {
    "getDevices": {"devices": [Device], "count": 123}
  }
}

Queries

`getPoi`

Response

Returns a Poi

Arguments

Name	Description
`id` - `Int!`	Identification of a poi - id. It's required.

Example

Query

query GetPoi($id: Int!) {
  getPoi(id: $id) {
    id
    slots {
      id
      poi {
        ...PoiFragment
      }
      device {
        ...DeviceFragment
      }
      parentId
      children {
        ...SlotFragment
      }
      parentSlot {
        ...SlotFragment
      }
      geometry {
        ...GeoJsonFragment
      }
    }
    geometry {
      type
      coordinates
    }
  }
}

Variables

{"id": 987}

Response

{
  "data": {
    "getPoi": {
      "id": "4",
      "slots": [Slot],
      "geometry": GeoJson
    }
  }
}

Queries

`getPois`

Description

Points of installation on a map. It's an infrastructure elements where you have connected IoT devices.

Response

Returns a Pois

Arguments

Name	Description
`skip` - `Int`	Skip and limit are useful for pagination. If not defined the default value (0) will be set. It's like a cursor to return records from range ( skip * limit, ( skip * limit ) + limit ). Default = `0`
`limit` - `Int`	Skip and limit are useful for pagination. If not defined the default value (100) will be set. It's like a cursor to return records from range ( skip * limit, ( skip * limit ) + limit ). Default = `100`

Example

Query

query GetPois(
  $skip: Int,
  $limit: Int
) {
  getPois(
    skip: $skip,
    limit: $limit
  ) {
    pois {
      id
      slots {
        ...SlotFragment
      }
      geometry {
        ...GeoJsonFragment
      }
    }
    count
  }
}

Variables

{"skip": 0, "limit": 100}

Response

{"data": {"getPois": {"pois": [Poi], "count": 987.65}}}

Mutations

`overrideLight`

Description

Set a light level for a device. Returns a commandId which can be used to retrive command success or failure using getCommandStatus query.

Response

Returns an Int!

Arguments

Name	Description
`command` - `LightCommand!`	The parameters for light override command such as a duration, light level
`components` - `[String!]!`	array of light component id's
`deviceUid` - `String!`	uid of the device

Example

Query

mutation OverrideLight(
  $command: LightCommand!,
  $components: [String!]!,
  $deviceUid: String!
) {
  overrideLight(
    command: $command,
    components: $components,
    deviceUid: $deviceUid
  )
}

Variables

{
  "command": LightCommand,
  "components": ["xyz789"],
  "deviceUid": "abc123"
}

Response

{"data": {"overrideLight": 987}}

Types

Alert

Description

A representation for single alert.

Fields

Field Name	Description
`severity` - `Int!`	Severity of an alert - info, warning, error, critical.
`type` - `String!`	Type of an alert.
`active` - `Boolean!`	An alert status - active, inactive.
`id` - `ID!`	An identification of alert
`confirmedBy` - `String!`	A user who confirmed an alert.
`tags` - `[String!]!`	An alert tags such as light, connectivity and so on.
`createdAt` - `DateTime!`	Timestamp when alert has been created.
`startedAt` - `DateTime!`	Timestamp when alert has been started.
`stoppedAt` - `DateTime`	Timestamp when alert has been stopped.
`confirmedAt` - `DateTime`	Timestamp when alert has been confirmed.

Example

{
  "severity": 987,
  "type": "xyz789",
  "active": true,
  "id": 4,
  "confirmedBy": "xyz789",
  "tags": ["xyz789"],
  "createdAt": "2007-12-03T10:15:30Z",
  "startedAt": "2007-12-03T10:15:30Z",
  "stoppedAt": "2007-12-03T10:15:30Z",
  "confirmedAt": "2007-12-03T10:15:30Z"
}

Types

AlertsCollection

Description

Device alerts list.

Fields

Field Name	Description
`alerts` - `[Alert!]`	Device alerts.
`count` - `Int!`	Number of device alerts.

Example

{"alerts": [Alert], "count": 123}

Types

AlertsFilter

Description

Alerts filter object - used in alerts queries.

Fields

Input Field	Description
`from` - `DateTime`	Time in miliseconds since 1970/01/01. Parameter is optional.
`to` - `DateTime`	Time in miliseconds since 1970/01/01. Parameter is optional.
`active` - `Boolean`	Get only active / inactive alerts. Parameter is optional.
`confirmed` - `Boolean`	Confirmation status - get only confirmed / unconfirmed alerts. Parameter is optional.

Example

{
  "from": "2007-12-03T10:15:30Z",
  "to": "2007-12-03T10:15:30Z",
  "active": true,
  "confirmed": true
}

Types

Boolean

Description

The Boolean scalar type represents true or false.

Example

true

Types

CameraComponent

Description

Camera connected to the device

Fields

Field Name	Description
`id` - `ID!`	Identification of camera component - id.
`lastValue` - `JSONObject`	Last values of camera properties

Example

{"id": 4, "lastValue": {}}

Types

Command

Description

A command response object where you find information about executed command.

Fields

Field Name	Description
`id` - `String!`	Command identification - id. Useful when you'd like to get command status. See getCommandStatus query.
`type` - `String!`	A command type - for example 'lightOverride'
`data` - `JSONObject`	Json object with received command specific data.
`response` - `JSONObject`	Json object with received command response.
`sent` - `DateTime!`	Timestamp when command has been sent.
`confirmed` - `DateTime`	Timestamp when command has been confirmed.
`timeout` - `DateTime`	Timestamp when command has been timed out. When not null it tells that this command will not be retried any more.

Example

{
  "id": "xyz789",
  "type": "xyz789",
  "data": {},
  "response": {},
  "sent": "2007-12-03T10:15:30Z",
  "confirmed": "2007-12-03T10:15:30Z",
  "timeout": "2007-12-03T10:15:30Z"
}

Types

DateTime

Description

The javascript Date as string. Type represents date and time as the ISO Date string.

Example

"2007-12-03T10:15:30Z"

Types

Device

Description

A representation of device in the system.

Fields

Field Name	Description
`id` - `ID!`	Device ID
`uid` - `String!`	Device UID - main identification for a lot of queries to the API.
`type` - `String!`	Devices type
`slot` - `Slot!`	Slot object where device is assigned with. See Slot object schema.
`createdAt` - `DateTime!`	Timestamp when device is created in a system.
`groups` - `[Group!]!`	Groups assigned to this device
`needsAttentionAlerts` - `[Alert!]!`	Collection of active or unconfirmed device alerts
`lightComponents` - `[LightComponent!]`	Light components
`meterComponents` - `[MeterComponent!]`	Power meter components
`cameraComponents` - `[CameraComponent!]`	Cameras connected to device
`motionSensors` - `[MotionSensor!]`	Motion sensor assigned to a device
`lightSensorComponents` - `[LightSensorComponent!]`	Light sensor components

Example

{
  "id": "4",
  "uid": "xyz789",
  "type": "xyz789",
  "slot": Slot,
  "createdAt": "2007-12-03T10:15:30Z",
  "groups": [Group],
  "needsAttentionAlerts": [Alert],
  "lightComponents": [LightComponent],
  "meterComponents": [MeterComponent],
  "cameraComponents": [CameraComponent],
  "motionSensors": [MotionSensor],
  "lightSensorComponents": [LightSensorComponent]
}

Types

Devices

Description

List of devices - response object where you can get by getDevices query.

Fields

Field Name	Description
`devices` - `[Device!]!`	List of devices.
`count` - `Int!`	Number of devices

Example

{"devices": [Device], "count": 987}

Types

Float

Description

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

Example

123.45

Types

GeoJson

Description

Geo json object where you find coordinates for an object on a map.

Fields

Field Name	Description
`type` - `String!`	See geojson standard and structure in the internet. Pois and slots has geometry of type Point.
`coordinates` - `[Float!]!`	Coordinates for a point.

Example

{"type": "xyz789", "coordinates": [123.45]}

Types

Group

Description

A representation of a group in the system. By this object we mean group of luminaires devices, not group of alerts.

Fields

Field Name	Description
`id` - `ID!`	An identification of a group - id.
`name` - `String!`	A group name.
`schedules` - `[Schedule!]`	Schedules assigned to group.

Example

{
  "id": 4,
  "name": "abc123",
  "schedules": [Schedule]
}

Types

ID

Description

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

Types

Int

Description

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

Example

Types

JSONObject

Description

The JSONObject scalar type represents JSON objects as specified by ECMA-404.

Example

{}

Types

LightCommand

Description

Light command object used in override light mutation.

Fields

Input Field	Description
`duration` - `Int!`	Duration of light override - defined in seconds, max 1 day
`level` - `Int!`	Level of light in percent.

Example

{"duration": 123, "level": 123}

Types

LightComponent

Description

A representation of light component object. It's required for light override where you can set light level.

Fields

Field Name	Description
`id` - `ID!`	An identification of light component.
`schedules` - `[Schedule!]`	Schedules assigned to current device
`lastValue` - `JSONObject`	Last values of light component properties

Example

{
  "id": "4",
  "schedules": [Schedule],
  "lastValue": {}
}

Types

LightSensorComponent

Description

A representation of light sensor component object.

Fields

Field Name	Description
`id` - `ID!`	Component id of a light sensor in a device.
`lastValue` - `JSONObject`	Last values of light sensor properties

Example

{"id": 4, "lastValue": {}}

Types

MeterComponent

Description

A representation of power meter component object.

Fields

Field Name	Description
`id` - `ID!`	Component id of a power meter in a device.
`lastValue` - `JSONObject`	Last values of power meter properties, can be different depends on power meter type
`type` - `String`	Type of connected power meter to the device

Example

{
  "id": "4",
  "lastValue": {},
  "type": "abc123"
}

Types

MotionSensor

Description

A representation of motion sensor object.

Fields

Field Name	Description
`id` - `ID!`	Motion sensor id.
`type` - `String!`	Type of a motion sensor.
`lastValue` - `JSONObject`	Last values of motion sensor properties

Example

{
  "id": "4",
  "type": "xyz789",
  "lastValue": {}
}

Types

Poi

Description

A representation of point of installation in the system.

Fields

Field Name	Description
`id` - `ID!`	Poi ID
`slots` - `[Slot!]`	Flat slot list for poi
`geometry` - `GeoJson`	Geo json geometry of point of installation in the system.

Example

{
  "id": 4,
  "slots": [Slot],
  "geometry": GeoJson
}

Types

Pois

Description

Points of installation in the system. Response object for a query getPois.

Fields

Field Name	Description
`pois` - `[Poi!]!`	Point of installation list
`count` - `Float!`	Number of pois.

Example

{"pois": [Poi], "count": 123.45}

Types

Schedule

Description

A representaion of a schedule object in a system.

Fields

Field Name	Description
`id` - `String!`	Schedule identification - id.
`name` - `String!`	Schedule name.

Example

{
  "id": "abc123",
  "name": "abc123"
}

Types

Slot

Description

A representation of slot object in a system.

Fields

Field Name	Description
`id` - `ID!`	Slot ID.
`poi` - `Poi!`	A point of installation where this slot is assigned with.
`device` - `Device`	Device installed in a slot.
`parentId` - `String`	Parent slot id.
`children` - `[Slot!]!`	Children slots of the current one
`parentSlot` - `Slot`	Parent slot of the current one.
`geometry` - `GeoJson`	Geometry of a slot. Could be nullable, because generally slot has the same geometry as poi. But system gives a possibility to have different geometry between poi and slot when you have two devices on a pole and you'd like to differentiate position to a left or right lane of the road.

Example

{
  "id": 4,
  "poi": Poi,
  "device": Device,
  "parentId": "xyz789",
  "children": [Slot],
  "parentSlot": Slot,
  "geometry": GeoJson
}

Types

String

Description

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.

Example

"xyz789"