Edgehog GraphQL API Reference

Welcome to the Edgehog GraphQL API reference! This reference includes the complete set of GraphQL types, queries, mutations, and their parameters for managing devices.

API Endpoints
http://localhost:4000/api

Queries

device

Description

Fetches a single device.

Response

Returns a Device

Arguments
Name Description
id - ID! The ID of the device.

Example

Query
query device($id: ID!) {
  device(id: $id) {
    id
    name
    deviceId
    online
    lastConnection
    lastDisconnection
    systemModel {
      ...SystemModelFragment
    }
    deviceGroups {
      ...DeviceGroupFragment
    }
    tags
    customAttributes {
      ...DeviceAttributeFragment
    }
    capabilities
    hardwareInfo {
      ...HardwareInfoFragment
    }
    location {
      ...DeviceLocationFragment
    }
    storageUsage {
      ...StorageUnitFragment
    }
    systemStatus {
      ...SystemStatusFragment
    }
    wifiScanResults {
      ...WifiScanResultFragment
    }
    batteryStatus {
      ...BatterySlotFragment
    }
    baseImage {
      ...BaseImageFragment
    }
    osInfo {
      ...OsInfoFragment
    }
    otaOperations {
      ...OtaOperationFragment
    }
    cellularConnection {
      ...ModemFragment
    }
    runtimeInfo {
      ...RuntimeInfoFragment
    }
  }
}
Variables
{"id": 4}
Response
{
  "data": {
    "device": {
      "id": "4",
      "name": "xyz789",
      "deviceId": "abc123",
      "online": false,
      "lastConnection": "2007-12-03T10:15:30Z",
      "lastDisconnection": "2007-12-03T10:15:30Z",
      "systemModel": SystemModel,
      "deviceGroups": [DeviceGroup],
      "tags": ["abc123"],
      "customAttributes": [DeviceAttribute],
      "capabilities": ["BASE_IMAGE"],
      "hardwareInfo": HardwareInfo,
      "location": DeviceLocation,
      "storageUsage": [StorageUnit],
      "systemStatus": SystemStatus,
      "wifiScanResults": [WifiScanResult],
      "batteryStatus": [BatterySlot],
      "baseImage": BaseImage,
      "osInfo": OsInfo,
      "otaOperations": [OtaOperation],
      "cellularConnection": [Modem],
      "runtimeInfo": RuntimeInfo
    }
  }
}

deviceGroup

Description

Fetches a single device group.

Response

Returns a DeviceGroup

Arguments
Name Description
id - ID! The ID of the device group.

Example

Query
query deviceGroup($id: ID!) {
  deviceGroup(id: $id) {
    id
    name
    handle
    selector
    devices {
      ...DeviceFragment
    }
  }
}
Variables
{"id": 4}
Response
{
  "data": {
    "deviceGroup": {
      "id": "4",
      "name": "abc123",
      "handle": "xyz789",
      "selector": "abc123",
      "devices": [Device]
    }
  }
}

deviceGroups

Description

Fetches the list of all device groups.

Response

Returns [DeviceGroup!]!

Example

Query
query deviceGroups {
  deviceGroups {
    id
    name
    handle
    selector
    devices {
      ...DeviceFragment
    }
  }
}
Response
{
  "data": {
    "deviceGroups": [
      {
        "id": "4",
        "name": "xyz789",
        "handle": "abc123",
        "selector": "xyz789",
        "devices": [Device]
      }
    ]
  }
}

devices

Description

Fetches the list of all devices.

Response

Returns [Device!]!

Arguments
Name Description
filter - DeviceFilter An optional set of filters to apply when fetching the devices.

Example

Query
query devices($filter: DeviceFilter) {
  devices(filter: $filter) {
    id
    name
    deviceId
    online
    lastConnection
    lastDisconnection
    systemModel {
      ...SystemModelFragment
    }
    deviceGroups {
      ...DeviceGroupFragment
    }
    tags
    customAttributes {
      ...DeviceAttributeFragment
    }
    capabilities
    hardwareInfo {
      ...HardwareInfoFragment
    }
    location {
      ...DeviceLocationFragment
    }
    storageUsage {
      ...StorageUnitFragment
    }
    systemStatus {
      ...SystemStatusFragment
    }
    wifiScanResults {
      ...WifiScanResultFragment
    }
    batteryStatus {
      ...BatterySlotFragment
    }
    baseImage {
      ...BaseImageFragment
    }
    osInfo {
      ...OsInfoFragment
    }
    otaOperations {
      ...OtaOperationFragment
    }
    cellularConnection {
      ...ModemFragment
    }
    runtimeInfo {
      ...RuntimeInfoFragment
    }
  }
}
Variables
{"filter": DeviceFilter}
Response
{
  "data": {
    "devices": [
      {
        "id": "4",
        "name": "abc123",
        "deviceId": "xyz789",
        "online": true,
        "lastConnection": "2007-12-03T10:15:30Z",
        "lastDisconnection": "2007-12-03T10:15:30Z",
        "systemModel": SystemModel,
        "deviceGroups": [DeviceGroup],
        "tags": ["abc123"],
        "customAttributes": [DeviceAttribute],
        "capabilities": ["BASE_IMAGE"],
        "hardwareInfo": HardwareInfo,
        "location": DeviceLocation,
        "storageUsage": [StorageUnit],
        "systemStatus": SystemStatus,
        "wifiScanResults": [WifiScanResult],
        "batteryStatus": [BatterySlot],
        "baseImage": BaseImage,
        "osInfo": OsInfo,
        "otaOperations": [OtaOperation],
        "cellularConnection": [Modem],
        "runtimeInfo": RuntimeInfo
      }
    ]
  }
}

existingDeviceTags

Description

Fetches the list of all device tags.

Response

Returns [String!]!

Example

Query
query existingDeviceTags {
  existingDeviceTags
}
Response
{"data": {"existingDeviceTags": ["abc123"]}}

hardwareType

Description

Fetches a single hardware type.

Response

Returns a HardwareType

Arguments
Name Description
id - ID! The ID of the hardware type.

Example

Query
query hardwareType($id: ID!) {
  hardwareType(id: $id) {
    id
    name
    handle
    partNumbers
  }
}
Variables
{"id": 4}
Response
{
  "data": {
    "hardwareType": {
      "id": 4,
      "name": "xyz789",
      "handle": "abc123",
      "partNumbers": ["abc123"]
    }
  }
}

hardwareTypes

Description

Fetches the list of all hardware types.

Response

Returns [HardwareType!]!

Example

Query
query hardwareTypes {
  hardwareTypes {
    id
    name
    handle
    partNumbers
  }
}
Response
{
  "data": {
    "hardwareTypes": [
      {
        "id": "4",
        "name": "abc123",
        "handle": "abc123",
        "partNumbers": ["xyz789"]
      }
    ]
  }
}

node

Response

Returns a Node

Arguments
Name Description
id - ID! The ID of an object.

Example

Query
query node($id: ID!) {
  node(id: $id) {
    id
  }
}
Variables
{"id": 4}
Response
{"data": {"node": {"id": "4"}}}

systemModel

Description

Fetches a single system model.

Response

Returns a SystemModel

Arguments
Name Description
id - ID! The ID of the system model.

Example

Query
query systemModel($id: ID!) {
  systemModel(id: $id) {
    id
    name
    handle
    pictureUrl
    hardwareType {
      ...HardwareTypeFragment
    }
    partNumbers
    description {
      ...LocalizedTextFragment
    }
  }
}
Variables
{"id": "4"}
Response
{
  "data": {
    "systemModel": {
      "id": 4,
      "name": "abc123",
      "handle": "xyz789",
      "pictureUrl": "abc123",
      "hardwareType": HardwareType,
      "partNumbers": ["xyz789"],
      "description": LocalizedText
    }
  }
}

systemModels

Description

Fetches the list of all system models.

Response

Returns [SystemModel!]!

Example

Query
query systemModels {
  systemModels {
    id
    name
    handle
    pictureUrl
    hardwareType {
      ...HardwareTypeFragment
    }
    partNumbers
    description {
      ...LocalizedTextFragment
    }
  }
}
Response
{
  "data": {
    "systemModels": [
      {
        "id": "4",
        "name": "abc123",
        "handle": "xyz789",
        "pictureUrl": "abc123",
        "hardwareType": HardwareType,
        "partNumbers": ["abc123"],
        "description": LocalizedText
      }
    ]
  }
}

tenantInfo

Description

Retrieves information about the current tenant

Response

Returns a TenantInfo!

Example

Query
query tenantInfo {
  tenantInfo {
    name
    slug
    defaultLocale
  }
}
Response
{
  "data": {
    "tenantInfo": {
      "name": "xyz789",
      "slug": "xyz789",
      "defaultLocale": "abc123"
    }
  }
}

Mutations

createDeviceGroup

Description

Creates a new device group.

Response

Returns a CreateDeviceGroupPayload

Arguments
Name Description
input - CreateDeviceGroupInput!

Example

Query
mutation createDeviceGroup($input: CreateDeviceGroupInput!) {
  createDeviceGroup(input: $input) {
    deviceGroup {
      ...DeviceGroupFragment
    }
  }
}
Variables
{"input": CreateDeviceGroupInput}
Response
{
  "data": {
    "createDeviceGroup": {"deviceGroup": DeviceGroup}
  }
}

createHardwareType

Description

Creates a new hardware type.

Response

Returns a CreateHardwareTypePayload

Arguments
Name Description
input - CreateHardwareTypeInput!

Example

Query
mutation createHardwareType($input: CreateHardwareTypeInput!) {
  createHardwareType(input: $input) {
    hardwareType {
      ...HardwareTypeFragment
    }
  }
}
Variables
{"input": CreateHardwareTypeInput}
Response
{
  "data": {
    "createHardwareType": {"hardwareType": HardwareType}
  }
}

createManualOtaOperation

Description

Initiates an OTA update with a user provided OS image

Response

Returns a CreateManualOtaOperationPayload

Arguments
Name Description
input - CreateManualOtaOperationInput!

Example

Query
mutation createManualOtaOperation($input: CreateManualOtaOperationInput!) {
  createManualOtaOperation(input: $input) {
    otaOperation {
      ...OtaOperationFragment
    }
  }
}
Variables
{"input": CreateManualOtaOperationInput}
Response
{
  "data": {
    "createManualOtaOperation": {
      "otaOperation": OtaOperation
    }
  }
}

createSystemModel

Description

Creates a new system model.

Response

Returns a CreateSystemModelPayload

Arguments
Name Description
input - CreateSystemModelInput!

Example

Query
mutation createSystemModel($input: CreateSystemModelInput!) {
  createSystemModel(input: $input) {
    systemModel {
      ...SystemModelFragment
    }
  }
}
Variables
{"input": CreateSystemModelInput}
Response
{
  "data": {
    "createSystemModel": {"systemModel": SystemModel}
  }
}

deleteDeviceGroup

Description

Deletes a device group.

Response

Returns a DeleteDeviceGroupPayload

Arguments
Name Description
input - DeleteDeviceGroupInput!

Example

Query
mutation deleteDeviceGroup($input: DeleteDeviceGroupInput!) {
  deleteDeviceGroup(input: $input) {
    deviceGroup {
      ...DeviceGroupFragment
    }
  }
}
Variables
{"input": DeleteDeviceGroupInput}
Response
{
  "data": {
    "deleteDeviceGroup": {"deviceGroup": DeviceGroup}
  }
}

deleteHardwareType

Description

Deletes a hardware type.

Response

Returns a DeleteHardwareTypePayload

Arguments
Name Description
input - DeleteHardwareTypeInput!

Example

Query
mutation deleteHardwareType($input: DeleteHardwareTypeInput!) {
  deleteHardwareType(input: $input) {
    hardwareType {
      ...HardwareTypeFragment
    }
  }
}
Variables
{"input": DeleteHardwareTypeInput}
Response
{
  "data": {
    "deleteHardwareType": {"hardwareType": HardwareType}
  }
}

deleteSystemModel

Description

Deletes a system model.

Response

Returns a DeleteSystemModelPayload

Arguments
Name Description
input - DeleteSystemModelInput!

Example

Query
mutation deleteSystemModel($input: DeleteSystemModelInput!) {
  deleteSystemModel(input: $input) {
    systemModel {
      ...SystemModelFragment
    }
  }
}
Variables
{"input": DeleteSystemModelInput}
Response
{
  "data": {
    "deleteSystemModel": {"systemModel": SystemModel}
  }
}

setLedBehavior

Description

Sets led behavior.

Response

Returns a SetLedBehaviorPayload

Arguments
Name Description
input - SetLedBehaviorInput!

Example

Query
mutation setLedBehavior($input: SetLedBehaviorInput!) {
  setLedBehavior(input: $input) {
    behavior
  }
}
Variables
{"input": SetLedBehaviorInput}
Response
{"data": {"setLedBehavior": {"behavior": "BLINK"}}}

updateDevice

Description

Updates a device.

Response

Returns an UpdateDevicePayload

Arguments
Name Description
input - UpdateDeviceInput!

Example

Query
mutation updateDevice($input: UpdateDeviceInput!) {
  updateDevice(input: $input) {
    device {
      ...DeviceFragment
    }
  }
}
Variables
{"input": UpdateDeviceInput}
Response
{"data": {"updateDevice": {"device": Device}}}

updateDeviceGroup

Description

Updates a device group.

Response

Returns an UpdateDeviceGroupPayload

Arguments
Name Description
input - UpdateDeviceGroupInput!

Example

Query
mutation updateDeviceGroup($input: UpdateDeviceGroupInput!) {
  updateDeviceGroup(input: $input) {
    deviceGroup {
      ...DeviceGroupFragment
    }
  }
}
Variables
{"input": UpdateDeviceGroupInput}
Response
{
  "data": {
    "updateDeviceGroup": {"deviceGroup": DeviceGroup}
  }
}

updateHardwareType

Description

Updates a hardware type.

Response

Returns an UpdateHardwareTypePayload

Arguments
Name Description
input - UpdateHardwareTypeInput!

Example

Query
mutation updateHardwareType($input: UpdateHardwareTypeInput!) {
  updateHardwareType(input: $input) {
    hardwareType {
      ...HardwareTypeFragment
    }
  }
}
Variables
{"input": UpdateHardwareTypeInput}
Response
{
  "data": {
    "updateHardwareType": {"hardwareType": HardwareType}
  }
}

updateSystemModel

Description

Updates a system model.

Response

Returns an UpdateSystemModelPayload

Arguments
Name Description
input - UpdateSystemModelInput!

Example

Query
mutation updateSystemModel($input: UpdateSystemModelInput!) {
  updateSystemModel(input: $input) {
    systemModel {
      ...SystemModelFragment
    }
  }
}
Variables
{"input": UpdateSystemModelInput}
Response
{
  "data": {
    "updateSystemModel": {"systemModel": SystemModel}
  }
}

Types

BaseImage

Description

Describes an operating system's base image for a device.

Fields
Field Name Description
name - String The name of the image.
version - String The version of the image.
buildId - String Human readable build identifier of the image.
fingerprint - String A unique string that identifies the release, usually the image hash.
Example
{
  "name": "xyz789",
  "version": "abc123",
  "buildId": "xyz789",
  "fingerprint": "xyz789"
}

BatterySlot

Description

Describes a battery slot of a device.

Fields
Field Name Description
slot - String! The identifier of the battery slot.
levelPercentage - Float Battery level estimated percentage [0.0%-100.0%]
levelAbsoluteError - Float Battery level measurement absolute error [0.0-100.0]
status - BatteryStatus The current status of the battery.
Example
{
  "slot": "xyz789",
  "levelPercentage": 987.65,
  "levelAbsoluteError": 987.65,
  "status": "CHARGING"
}

BatteryStatus

Description

The current status of the battery.

Values
Enum Value Description

CHARGING

The battery is charging.

DISCHARGING

The battery is discharging.

IDLE

The battery is idle.

EITHER_IDLE_OR_CHARGING

The battery is either in a charging or in an idle state, since the hardware doesn't allow to distinguish between them.

FAILURE

The battery is in a failed state.

REMOVED

The battery is removed.

UNKNOWN

The battery status cannot be determined.
Example
"CHARGING"

Boolean

Description

The Boolean scalar type represents true or false.

CreateDeviceGroupInput

Fields
Input Field Description
name - String!

The display name of the device group.

handle - String!

The identifier of the device group.

It should start with a lower case ASCII letter and only contain lower case ASCII letters, digits and the hyphen - symbol.

selector - String!

The Selector that will determine which devices belong to the device group.

This must be a valid selector expression, consult the Selector section of the Edgehog documentation for more information about Selectors.

Example
{
  "name": "xyz789",
  "handle": "xyz789",
  "selector": "abc123"
}

CreateDeviceGroupPayload

Fields
Field Name Description
deviceGroup - DeviceGroup! The created device group.
Example
{"deviceGroup": DeviceGroup}

CreateHardwareTypeInput

Fields
Input Field Description
name - String!

The display name of the hardware type.

handle - String!

The identifier of the hardware type.

It should start with a lower case ASCII letter and only contain lower case ASCII letters, digits and the hyphen - symbol.

partNumbers - [String!]!

The list of part numbers associated with the hardware type.

Example
{
  "name": "xyz789",
  "handle": "xyz789",
  "partNumbers": ["xyz789"]
}

CreateHardwareTypePayload

Fields
Field Name Description
hardwareType - HardwareType! The created hardware type.
Example
{"hardwareType": HardwareType}

CreateManualOtaOperationInput

Fields
Input Field Description
deviceId - ID!

The GraphQL ID (not the Astarte Device ID) of the target device

baseImageFile - Upload

An uploaded file of the base image.

Example
{
  "deviceId": "4",
  "baseImageFile": Upload
}

CreateManualOtaOperationPayload

Fields
Field Name Description
otaOperation - OtaOperation! The pending OTA operation
Example
{"otaOperation": OtaOperation}

CreateSystemModelInput

Fields
Input Field Description
name - String!

The display name of the system model.

handle - String!

The identifier of the system model.

It should start with a lower case ASCII letter and only contain lower case ASCII letters, digits and the hyphen - symbol.

pictureFile - Upload

The file blob of a related picture.

When this field is specified, the pictureUrl field is ignored.

pictureUrl - String

The file URL of a related picture.

Specifying a null value will remove the existing picture. When the pictureFile field is specified, this field is ignored.

partNumbers - [String!]!

The list of part numbers associated with the system model.

hardwareTypeId - ID!

The ID of the hardware type that can be used by devices of this model.

description - LocalizedTextInput

An optional localized description. This description can only use the default tenant locale.

Example
{
  "name": "abc123",
  "handle": "xyz789",
  "pictureFile": Upload,
  "pictureUrl": "abc123",
  "partNumbers": ["xyz789"],
  "hardwareTypeId": 4,
  "description": LocalizedTextInput
}

CreateSystemModelPayload

Fields
Field Name Description
systemModel - SystemModel! The created system model.
Example
{"systemModel": SystemModel}

DateTime

Description

The DateTime scalar type represents a date and time in the UTC timezone. The DateTime appears in a JSON response as an ISO8601 formatted string, including UTC timezone ("Z"). The parsed date and time string will be converted to UTC if there is an offset.

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

DeleteDeviceGroupInput

Fields
Input Field Description
deviceGroupId - ID!

The ID of the device group to be deleted.

Example
{"deviceGroupId": "4"}

DeleteDeviceGroupPayload

Fields
Field Name Description
deviceGroup - DeviceGroup! The deleted device group.
Example
{"deviceGroup": DeviceGroup}

DeleteHardwareTypeInput

Fields
Input Field Description
hardwareTypeId - ID!

The ID of the hardware type to be deleted.

Example
{"hardwareTypeId": 4}

DeleteHardwareTypePayload

Fields
Field Name Description
hardwareType - HardwareType! The deleted hardware type.
Example
{"hardwareType": HardwareType}

DeleteSystemModelInput

Fields
Input Field Description
systemModelId - ID!

The ID of the system model to be deleted.

Example
{"systemModelId": "4"}

DeleteSystemModelPayload

Fields
Field Name Description
systemModel - SystemModel! The deleted system model.
Example
{"systemModel": SystemModel}

Device

Description

Denotes a device instance that connects and exchanges data.

Each Device is associated to a specific SystemModel, which in turn is associated to a specific HardwareType. A Device also exposes info about its connection status and some sets of data read by its operating system.

Fields
Field Name Description
id - ID! The ID of an object
name - String! The display name of the device.
deviceId - String! The device ID used to connect to the Astarte cluster.
online - Boolean! Tells whether the device is connected or not to Astarte.
lastConnection - DateTime The date at which the device last connected to Astarte.
lastDisconnection - DateTime The date at which the device last disconnected from Astarte.
systemModel - SystemModel The system model of the device.
deviceGroups - [DeviceGroup!]! The device groups the device belongs to.
tags - [String!]! The tags of the device
customAttributes - [DeviceAttribute!]! The custom attributes of the device. These attributes are user editable.
capabilities - [DeviceCapability!]! List of capabilities supported by the device.
hardwareInfo - HardwareInfo Info read from the device's hardware.
location - DeviceLocation The estimated location of the device.
storageUsage - [StorageUnit!] The current usage of the storage units of the device.
systemStatus - SystemStatus The current status of the operating system of the device.
wifiScanResults - [WifiScanResult!] The list of WiFi Access Points found by the device.
batteryStatus - [BatterySlot!] The status of the battery slots of the device.
baseImage - BaseImage Information about the operating system's base image for the device.
osInfo - OsInfo Information about the operating system of the device.
otaOperations - [OtaOperation!]! The existing OTA operations for this device
cellularConnection - [Modem!] The status of cellular connection of the device.
runtimeInfo - RuntimeInfo Information about the Edgehog runtime running on the device.
Example
{
  "id": "4",
  "name": "xyz789",
  "deviceId": "xyz789",
  "online": false,
  "lastConnection": "2007-12-03T10:15:30Z",
  "lastDisconnection": "2007-12-03T10:15:30Z",
  "systemModel": SystemModel,
  "deviceGroups": [DeviceGroup],
  "tags": ["xyz789"],
  "customAttributes": [DeviceAttribute],
  "capabilities": ["BASE_IMAGE"],
  "hardwareInfo": HardwareInfo,
  "location": DeviceLocation,
  "storageUsage": [StorageUnit],
  "systemStatus": SystemStatus,
  "wifiScanResults": [WifiScanResult],
  "batteryStatus": [BatterySlot],
  "baseImage": BaseImage,
  "osInfo": OsInfo,
  "otaOperations": [OtaOperation],
  "cellularConnection": [Modem],
  "runtimeInfo": RuntimeInfo
}

DeviceAttribute

Fields
Field Name Description
namespace - DeviceAttributeNamespace! The namespace of the device attribute.
key - String! The key of the device attribute.
type - VariantType! The type of the device attribute.
value - VariantValue! The value of the device attribute.
Example
{
  "namespace": "CUSTOM",
  "key": "xyz789",
  "type": "DOUBLE",
  "value": VariantValue
}

DeviceAttributeInput

Description

An input object for a device attribute.

Fields
Input Field Description
namespace - DeviceAttributeNamespace!

The namespace of the device attribute.

key - String!

The key of the device attribute.

type - VariantType!

The type of the device attribute.

value - VariantValue!

The value of the device attribute.

Example
{
  "namespace": "CUSTOM",
  "key": "xyz789",
  "type": "DOUBLE",
  "value": VariantValue
}

DeviceAttributeNamespace

Description

The possible namespace values for device attributes

Values
Enum Value Description

CUSTOM

Custom attributes, user defined
Example
"CUSTOM"

DeviceCapability

Description

The capabilities that devices can support

Values
Enum Value Description

BASE_IMAGE

The device provides information about its base image.

BATTERY_STATUS

The device provides information about its battery status.

CELLULAR_CONNECTION

The device provides information about its cellular connection.

COMMANDS

The device supports commands, for example the rebooting command.

GEOLOCATION

The device can be geolocated.

HARDWARE_INFO

The device provides information about its hardware.

LED_BEHAVIORS

The device can be asked to blink its LED in a specific pattern.

NETWORK_INTERFACE_INFO

The device can provide information about its network interfaces.

OPERATING_SYSTEM

The device provides information about its operating system.

RUNTIME_INFO

The device provides information about its runtime.

SOFTWARE_UPDATES

The device can be updated remotely.

STORAGE

The device provides information about its storage units.

SYSTEM_INFO

The device provides information about its system.

SYSTEM_STATUS

The device provides information about its system status.

TELEMETRY_CONFIG

The device telemetry can be configured.

WIFI

The device provides information about surrounding WiFi APs.
Example
"BASE_IMAGE"

DeviceFilter

Description

Describes a set of filters to apply when fetching a list of devices.

When multiple filters are specified, they are applied in an AND fashion to further refine the results.

Fields
Input Field Description
online - Boolean

Whether to return devices connected or not to Astarte.

deviceId - String

A string to match against the device ID. The match is case-insensitive and tests whether the string is included in the device ID.

systemModelPartNumber - String

A string to match against the part number of the device's system model. The match is case-insensitive and tests whether the string is included in the part number of the device's system model.

systemModelHandle - String

A string to match against the handle of the device's system model. The match is case-insensitive and tests whether the string is included in the handle of the device's system model.

systemModelName - String

A string to match against the name of the device's system model. The match is case-insensitive and tests whether the string is included in the name of the device's system model.

hardwareTypePartNumber - String

A string to match against the part number of the device's hardware type. The match is case-insensitive and tests whether the string is included in the part number of the device's hardware type.

hardwareTypeHandle - String

A string to match against the handle of the device's hardware type. The match is case-insensitive and tests whether the string is included in the handle of the device's hardware type.

hardwareTypeName - String

A string to match against the name of the device's hardware type. The match is case-insensitive and tests whether the string is included in the name of the device's hardware type.

tag - String

A string to match against the tags of the device. The match is case-insensitive and tests whether the string is included in one of the tags of the device.

Example
{
  "online": false,
  "deviceId": "xyz789",
  "systemModelPartNumber": "xyz789",
  "systemModelHandle": "abc123",
  "systemModelName": "xyz789",
  "hardwareTypePartNumber": "xyz789",
  "hardwareTypeHandle": "abc123",
  "hardwareTypeName": "xyz789",
  "tag": "abc123"
}

DeviceGroup

Fields
Field Name Description
id - ID! The ID of an object
name - String! The display name of the device group.
handle - String! The handle of the device group.
selector - String! The selector of the device group.
devices - [Device!]! The devices belonging to the group.
Example
{
  "id": 4,
  "name": "abc123",
  "handle": "xyz789",
  "selector": "xyz789",
  "devices": [Device]
}

DeviceLocation

Description

Describes the position of a device.

The position is estimated by means of Edgehog's Geolocation modules and the data published by the device.

Fields
Field Name Description
latitude - Float! The latitude coordinate.
longitude - Float! The longitude coordinate.
accuracy - Float The accuracy of the measurement, in meters.
address - String The formatted address estimated for the position.
timestamp - DateTime! The date at which the measurement was made.
Example
{
  "latitude": 123.45,
  "longitude": 123.45,
  "accuracy": 987.65,
  "address": "xyz789",
  "timestamp": "2007-12-03T10:15:30Z"
}

Float

Description

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

Example
123.45

HardwareInfo

Description

Describes hardware-related info of a device.

It exposes data read by a device's operating system about the underlying hardware.

Fields
Field Name Description
cpuArchitecture - String The architecture of the CPU.
cpuModel - String The reference code of the CPU model.
cpuModelName - String The display name of the CPU model.
cpuVendor - String The vendor's name.
memoryTotalBytes - Int The Bytes count of memory.
Example
{
  "cpuArchitecture": "abc123",
  "cpuModel": "abc123",
  "cpuModelName": "abc123",
  "cpuVendor": "abc123",
  "memoryTotalBytes": 987
}

HardwareType

Description

Denotes a type of hardware that devices can have.

It refers to the physical components embedded in a device. This can represent, e.g., multiple revisions of a PCB (each with a different part number) which are functionally equivalent from the device point of view.

Fields
Field Name Description
id - ID! The ID of an object
name - String! The display name of the hardware type.
handle - String! The identifier of the hardware type.
partNumbers - [String!]! The list of part numbers associated with the hardware type.
Example
{
  "id": "4",
  "name": "abc123",
  "handle": "abc123",
  "partNumbers": ["abc123"]
}

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
4

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
987

LedBehavior

Description

Led behavior

Values
Enum Value Description

BLINK

Blink for 60 seconds.

DOUBLE_BLINK

Double blink for 60 seconds.

SLOW_BLINK

Slow blink for 60 seconds.
Example
"BLINK"

LocalizedText

Description

A text expressed in a specific locale.

Fields
Field Name Description
locale - String! The locale, expressed in the format indicated in RFC 5646 (e.g. en-US)
text - String! The localized text
Example
{
  "locale": "xyz789",
  "text": "xyz789"
}

LocalizedTextInput

Description

Input object used to provide a localizedText as an input.

Fields
Input Field Description
locale - String!

The locale, expressed in the format indicated in RFC 5646 (e.g. en-US)

text - String!

The localized text

Example
{
  "locale": "xyz789",
  "text": "abc123"
}

Modem

Description

Describes a modem of a device.

Fields
Field Name Description
slot - String! The identifier of the modem.
apn - String The operator apn address.
imei - String The modem IMEI code.
imsi - String The SIM IMSI code.
carrier - String Carrier operator name.
cellId - Int Unique identifier of the cell.
mobileCountryCode - Int The cell tower's Mobile Country Code (MCC).
mobileNetworkCode - Int The cell tower's Mobile Network Code.
localAreaCode - Int The Local Area Code.
registrationStatus - ModemRegistrationStatus The current registration status of the modem.
rssi - Float Signal strength in dBm.
technology - ModemTechnology Access Technology
Example
{
  "slot": "xyz789",
  "apn": "xyz789",
  "imei": "abc123",
  "imsi": "xyz789",
  "carrier": "xyz789",
  "cellId": 123,
  "mobileCountryCode": 123,
  "mobileNetworkCode": 123,
  "localAreaCode": 123,
  "registrationStatus": "NOT_REGISTERED",
  "rssi": 987.65,
  "technology": "GSM"
}

ModemRegistrationStatus

Description

The current GSM/LTE registration status of the modem.

Values
Enum Value Description

NOT_REGISTERED

Not registered, modem is not currently searching a new operator to register to.

REGISTERED

Registered, home network.

SEARCHING_OPERATOR

Not registered, but modem is currently searching a new operator to register to.

REGISTRATION_DENIED

Registration denied.

UNKNOWN

Unknown (e.g. out of GERAN/UTRAN/E-UTRAN coverage).

REGISTERED_ROAMING

Registered, roaming.
Example
"NOT_REGISTERED"

ModemTechnology

Description

The current access technology of the serving cell.

Values
Enum Value Description

GSM

GSM.

GSM_COMPACT

GSM Compact.

UTRAN

UTRAN.

GSM_EGPRS

GSM with EGPRS.

UTRAN_HSDPA

UTRAN with HSDPA.

UTRAN_HSUPA

UTRAN with HSUPA.

UTRAN_HSDPA_HSUPA

UTRAN with HSDPA and HSUPA.

EUTRAN

E-UTRAN.
Example
"GSM"

Node

Fields
Field Name Description
id - ID! The ID of the object.
Example
{"id": "4"}

OsInfo

Description

Describes an operating system of a device.

Fields
Field Name Description
name - String The name of the operating system.
version - String The version of the operating system.
Example
{
  "name": "xyz789",
  "version": "abc123"
}

OtaOperation

Description

An OTA update operation

Fields
Field Name Description
id - ID! The ID of an object
baseImageUrl - String! The URL of the base image being installed on the device
status - OtaOperationStatus! The current status of the operation
statusCode - OtaOperationStatusCode The current status code of the operation
device - Device! The device targeted from the operation
createdAt - DateTime! The creation timestamp of the operation
updatedAt - DateTime! The timestamp of the last update to the operation
Example
{
  "id": 4,
  "baseImageUrl": "abc123",
  "status": "PENDING",
  "statusCode": "NETWORK_ERROR",
  "device": Device,
  "createdAt": "2007-12-03T10:15:30Z",
  "updatedAt": "2007-12-03T10:15:30Z"
}

OtaOperationStatus

Description

Status of the OTA operation.

Values
Enum Value Description

PENDING

The OTA operation was created and is waiting an acknowledgment from the device

IN_PROGRESS

The OTA operation was accepted from the device

ERROR

The OTA operation ended with an error

DONE

The OTA operation ended succesfully
Example
"PENDING"

OtaOperationStatusCode

Description

Status code of the OTA operation.

Values
Enum Value Description

NETWORK_ERROR

A network error was encountered

NVS_ERROR

An NVS error was encountered

ALREADY_IN_PROGRESS

The OTA operation is already in progress

FAILED

The OTA operation has failed

DEPLOY_ERROR

A deploy error was encountered

WRONG_PARTITION

A boot partition error was encountered
Example
"NETWORK_ERROR"

RuntimeInfo

Description

Describes an Edgehog runtime.

Fields
Field Name Description
name - String The name of the Edgehog runtime.
version - String The version of the Edgehog runtime.
environment - String The environment of the Edgehog runtime.
url - String The URL that uniquely identifies the Edgehog runtime implementation.
Example
{
  "name": "abc123",
  "version": "xyz789",
  "environment": "xyz789",
  "url": "abc123"
}

SetLedBehaviorInput

Fields
Input Field Description
deviceId - ID!

The GraphQL ID (not the Astarte Device ID) of the target device

behavior - LedBehavior!

The led behavior

Example
{"deviceId": 4, "behavior": "BLINK"}

SetLedBehaviorPayload

Fields
Field Name Description
behavior - LedBehavior! The resulting led behavior.
Example
{"behavior": "BLINK"}

StorageUnit

Description

Describes the current usage of a storage unit on a device.

Fields
Field Name Description
label - String! The label of the storage unit.
totalBytes - Int The total number of bytes of the storage unit.
freeBytes - Int The number of free bytes of the storage unit.
Example
{
  "label": "abc123",
  "totalBytes": 123,
  "freeBytes": 987
}

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"

SystemModel

Description

Represents a specific system model.

A system model corresponds to what the users thinks as functionally equivalent devices (e.g. two revisions of a device containing two different embedded chips but having the same enclosure and the same functionality).Each SystemModel must be associated to a specific HardwareType.

Fields
Field Name Description
id - ID! The ID of an object
name - String! The display name of the system model.
handle - String! The identifier of the system model.
pictureUrl - String The URL of the related picture.
hardwareType - HardwareType! The type of hardware that can be plugged into the system model.
partNumbers - [String!]! The list of part numbers associated with the system model.
description - LocalizedText A localized description of the system model. The language of the description can be controlled passing an Accept-Language header in the request. If no such header is present, the default tenant language is returned.
Example
{
  "id": 4,
  "name": "abc123",
  "handle": "abc123",
  "pictureUrl": "abc123",
  "hardwareType": HardwareType,
  "partNumbers": ["xyz789"],
  "description": LocalizedText
}

SystemStatus

Description

Describes the current status of the operating system of a device.

Fields
Field Name Description
bootId - String The identifier of the performed boot sequence.
memoryFreeBytes - Int The number of free bytes of memory.
taskCount - Int The number of running tasks on the system.
uptimeMilliseconds - Int The number of milliseconds since the last system boot.
timestamp - DateTime! The date at which the system status was read.
Example
{
  "bootId": "xyz789",
  "memoryFreeBytes": 987,
  "taskCount": 123,
  "uptimeMilliseconds": 123,
  "timestamp": "2007-12-03T10:15:30Z"
}

TenantInfo

Description

Represents information about a tenant

Fields
Field Name Description
name - String! The tenant name
slug - String! The tenant slug
defaultLocale - String! The default locale supported by the tenant
Example
{
  "name": "abc123",
  "slug": "xyz789",
  "defaultLocale": "xyz789"
}

UpdateDeviceGroupInput

Fields
Input Field Description
deviceGroupId - ID!

The ID of the device group to be updated.

name - String

The display name of the device group.

handle - String

The identifier of the device group.

It should start with a lower case ASCII letter and only contain lower case ASCII letters, digits and the hyphen - symbol.

selector - String

The Selector that will determine which devices belong to the device group.

This must be a valid selector expression, consult the Selector section of the Edgehog documentation for more information about Selectors.

Example
{
  "deviceGroupId": "4",
  "name": "xyz789",
  "handle": "xyz789",
  "selector": "xyz789"
}

UpdateDeviceGroupPayload

Fields
Field Name Description
deviceGroup - DeviceGroup! The updated device group.
Example
{"deviceGroup": DeviceGroup}

UpdateDeviceInput

Fields
Input Field Description
deviceId - ID!

The GraphQL ID (not the Astarte Device ID) of the device to be updated.

name - String

The display name of the device.

tags - [String!]

The tags of the device. These replace all the current tags.

customAttributes - [DeviceAttributeInput!]

The custom attributes of the device. These replace all the current custom attributes.

Example
{
  "deviceId": 4,
  "name": "xyz789",
  "tags": ["abc123"],
  "customAttributes": [DeviceAttributeInput]
}

UpdateDevicePayload

Fields
Field Name Description
device - Device! The updated device.
Example
{"device": Device}

UpdateHardwareTypeInput

Fields
Input Field Description
hardwareTypeId - ID!

The ID of the hardware type to be updated.

name - String

The display name of the hardware type.

handle - String

The identifier of the hardware type.

It should start with a lower case ASCII letter and only contain lower case ASCII letters, digits and the hyphen - symbol.

partNumbers - [String!]

The list of part numbers associated with the hardware type.

Example
{
  "hardwareTypeId": "4",
  "name": "xyz789",
  "handle": "abc123",
  "partNumbers": ["abc123"]
}

UpdateHardwareTypePayload

Fields
Field Name Description
hardwareType - HardwareType! The updated hardware type.
Example
{"hardwareType": HardwareType}

UpdateSystemModelInput

Fields
Input Field Description
systemModelId - ID!

The ID of the system model to be updated.

name - String

The display name of the system model.

handle - String

The identifier of the system model.

It should start with a lower case ASCII letter and only contain lower case ASCII letters, digits and the hyphen - symbol.

pictureFile - Upload

The file blob of a related picture.

When this field is specified, the pictureUrl field is ignored.

pictureUrl - String

The file URL of a related picture.

Specifying a null value will remove the existing picture. When the pictureFile field is specified, this field is ignored.

partNumbers - [String!]

The list of part numbers associated with the system model.

description - LocalizedTextInput

An optional localized description. This description can only use the default tenant locale.

Example
{
  "systemModelId": "4",
  "name": "abc123",
  "handle": "xyz789",
  "pictureFile": Upload,
  "pictureUrl": "xyz789",
  "partNumbers": ["xyz789"],
  "description": LocalizedTextInput
}

UpdateSystemModelPayload

Fields
Field Name Description
systemModel - SystemModel! The updated system model.
Example
{"systemModel": SystemModel}

Upload

Description

Represents an uploaded file.

Example
Upload

VariantType

Values
Enum Value Description

DOUBLE

Double type

INTEGER

32 bit integer type

BOOLEAN

Boolean type

LONGINTEGER

64 bit integer type. When this is the type, the value will be a string representing the number. This is done to avoid representation errors when using JSON Numbers.

STRING

String type

BINARYBLOB

Binary blob type. When this is the type, the value will be Base64 encoded.

DATETIME

Datetime type. When this is the type, the value will be an ISO8601 timestamp.
Example
"DOUBLE"

VariantValue

Description

A variant value. It can contain any JSON value. The value will be checked together with the type to verify whether it's valid.

Example
VariantValue

WifiScanResult

Description

Describes the list of WiFi Access Points found by the device.

Fields
Field Name Description
channel - Int The channel used by the Access Point.
connected - Boolean Indicates whether the device is connected to the Access Point.
essid - String The ESSID advertised by the Access Point.
macAddress - String The MAC address advertised by the Access Point.
rssi - Int The power of the radio signal, measured in dBm.
timestamp - DateTime! The date at which the device found the Access Point.
Example
{
  "channel": 987,
  "connected": false,
  "essid": "abc123",
  "macAddress": "abc123",
  "rssi": 123,
  "timestamp": "2007-12-03T10:15:30Z"
}