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

baseImage

Description

Fetches a single base image.

Response

Returns a BaseImage

Arguments
Name Description
id - ID! The ID of the base image.

Example

Query
query baseImage($id: ID!) {
  baseImage(id: $id) {
    id
    version
    url
    startingVersionRequirement
    description
    releaseDisplayName
    baseImageCollection {
      ...BaseImageCollectionFragment
    }
  }
}
Variables
{"id": "4"}
Response
{
  "data": {
    "baseImage": {
      "id": 4,
      "version": "abc123",
      "url": "abc123",
      "startingVersionRequirement": "xyz789",
      "description": "abc123",
      "releaseDisplayName": "xyz789",
      "baseImageCollection": BaseImageCollection
    }
  }
}

baseImageCollection

Description

Fetches a single base image collection.

Response

Returns a BaseImageCollection

Arguments
Name Description
id - ID! The ID of the base image collection.

Example

Query
query baseImageCollection($id: ID!) {
  baseImageCollection(id: $id) {
    id
    name
    handle
    systemModel {
      ...SystemModelFragment
    }
    baseImages {
      ...BaseImageFragment
    }
  }
}
Variables
{"id": "4"}
Response
{
  "data": {
    "baseImageCollection": {
      "id": 4,
      "name": "abc123",
      "handle": "xyz789",
      "systemModel": SystemModel,
      "baseImages": [BaseImage]
    }
  }
}

baseImageCollections

Description

Fetches the list of all base image collections.

Response

Returns [BaseImageCollection!]!

Example

Query
query baseImageCollections {
  baseImageCollections {
    id
    name
    handle
    systemModel {
      ...SystemModelFragment
    }
    baseImages {
      ...BaseImageFragment
    }
  }
}
Response
{
  "data": {
    "baseImageCollections": [
      {
        "id": 4,
        "name": "xyz789",
        "handle": "xyz789",
        "systemModel": SystemModel,
        "baseImages": [BaseImage]
      }
    ]
  }
}

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 {
      ...BaseImageInfoFragment
    }
    osInfo {
      ...OsInfoFragment
    }
    otaOperations {
      ...OtaOperationFragment
    }
    cellularConnection {
      ...ModemFragment
    }
    runtimeInfo {
      ...RuntimeInfoFragment
    }
    networkInterfaces {
      ...NetworkInterfaceFragment
    }
  }
}
Variables
{"id": 4}
Response
{
  "data": {
    "device": {
      "id": "4",
      "name": "xyz789",
      "deviceId": "abc123",
      "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": BaseImageInfo,
      "osInfo": OsInfo,
      "otaOperations": [OtaOperation],
      "cellularConnection": [Modem],
      "runtimeInfo": RuntimeInfo,
      "networkInterfaces": [NetworkInterface]
    }
  }
}

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
    }
    updateChannel {
      ...UpdateChannelFragment
    }
  }
}
Variables
{"id": "4"}
Response
{
  "data": {
    "deviceGroup": {
      "id": 4,
      "name": "abc123",
      "handle": "xyz789",
      "selector": "abc123",
      "devices": [Device],
      "updateChannel": UpdateChannel
    }
  }
}

deviceGroups

Description

Fetches the list of all device groups.

Response

Returns [DeviceGroup!]!

Example

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

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 {
      ...BaseImageInfoFragment
    }
    osInfo {
      ...OsInfoFragment
    }
    otaOperations {
      ...OtaOperationFragment
    }
    cellularConnection {
      ...ModemFragment
    }
    runtimeInfo {
      ...RuntimeInfoFragment
    }
    networkInterfaces {
      ...NetworkInterfaceFragment
    }
  }
}
Variables
{"filter": DeviceFilter}
Response
{
  "data": {
    "devices": [
      {
        "id": 4,
        "name": "abc123",
        "deviceId": "abc123",
        "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": BaseImageInfo,
        "osInfo": OsInfo,
        "otaOperations": [OtaOperation],
        "cellularConnection": [Modem],
        "runtimeInfo": RuntimeInfo,
        "networkInterfaces": [NetworkInterface]
      }
    ]
  }
}

existingDeviceTags

Description

Fetches the list of all device tags.

Response

Returns [String!]!

Example

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

forwarderConfig

Description

Fetches the forwarder config, if available. Without a configuration, forwarding functionalities are not available.

Response

Returns a ForwarderConfig

Example

Query
query forwarderConfig {
  forwarderConfig {
    hostname
    port
    secureSessions
  }
}
Response
{
  "data": {
    "forwarderConfig": {
      "hostname": "xyz789",
      "port": 123,
      "secureSessions": false
    }
  }
}

forwarderSession

Description

Fetches a forwarder session by its token and the device ID.

Response

Returns a ForwarderSession

Arguments
Name Description
deviceId - ID! The GraphQL ID of the device corresponding to the session.
sessionToken - String! The token that identifies the session.

Example

Query
query forwarderSession(
  $deviceId: ID!,
  $sessionToken: String!
) {
  forwarderSession(
    deviceId: $deviceId,
    sessionToken: $sessionToken
  ) {
    token
    status
    secure
    forwarderHostname
    forwarderPort
  }
}
Variables
{
  "deviceId": "4",
  "sessionToken": "abc123"
}
Response
{
  "data": {
    "forwarderSession": {
      "token": "xyz789",
      "status": "CONNECTED",
      "secure": false,
      "forwarderHostname": "xyz789",
      "forwarderPort": 987
    }
  }
}

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": "xyz789",
      "partNumbers": ["xyz789"]
    }
  }
}

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": "xyz789",
        "handle": "xyz789",
        "partNumbers": ["abc123"]
      }
    ]
  }
}

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
  }
}
Variables
{"id": "4"}
Response
{
  "data": {
    "systemModel": {
      "id": "4",
      "name": "abc123",
      "handle": "abc123",
      "pictureUrl": "xyz789",
      "hardwareType": HardwareType,
      "partNumbers": ["abc123"],
      "description": "abc123"
    }
  }
}

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
  }
}
Response
{
  "data": {
    "systemModels": [
      {
        "id": "4",
        "name": "abc123",
        "handle": "xyz789",
        "pictureUrl": "abc123",
        "hardwareType": HardwareType,
        "partNumbers": ["abc123"],
        "description": "abc123"
      }
    ]
  }
}

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": "xyz789"
    }
  }
}

updateCampaign

Description

Fetches a single update campaign.

Response

Returns an UpdateCampaign

Arguments
Name Description
id - ID! The ID of the update campaign.

Example

Query
query updateCampaign($id: ID!) {
  updateCampaign(id: $id) {
    id
    name
    status
    outcome
    rolloutMechanism {
      ... on PushRollout {
        ...PushRolloutFragment
      }
    }
    baseImage {
      ...BaseImageFragment
    }
    updateChannel {
      ...UpdateChannelFragment
    }
    updateTargets {
      ...UpdateTargetFragment
    }
    stats {
      ...UpdateCampaignStatsFragment
    }
  }
}
Variables
{"id": 4}
Response
{
  "data": {
    "updateCampaign": {
      "id": 4,
      "name": "xyz789",
      "status": "IDLE",
      "outcome": "SUCCESS",
      "rolloutMechanism": PushRollout,
      "baseImage": BaseImage,
      "updateChannel": UpdateChannel,
      "updateTargets": [UpdateTarget],
      "stats": UpdateCampaignStats
    }
  }
}

updateCampaigns

Description

Fetches the list of all update campaigns. Newer update campaigns are returned first.

Response

Returns [UpdateCampaign!]!

Example

Query
query updateCampaigns {
  updateCampaigns {
    id
    name
    status
    outcome
    rolloutMechanism {
      ... on PushRollout {
        ...PushRolloutFragment
      }
    }
    baseImage {
      ...BaseImageFragment
    }
    updateChannel {
      ...UpdateChannelFragment
    }
    updateTargets {
      ...UpdateTargetFragment
    }
    stats {
      ...UpdateCampaignStatsFragment
    }
  }
}
Response
{
  "data": {
    "updateCampaigns": [
      {
        "id": 4,
        "name": "xyz789",
        "status": "IDLE",
        "outcome": "SUCCESS",
        "rolloutMechanism": PushRollout,
        "baseImage": BaseImage,
        "updateChannel": UpdateChannel,
        "updateTargets": [UpdateTarget],
        "stats": UpdateCampaignStats
      }
    ]
  }
}

updateChannel

Description

Fetches a single update channel.

Response

Returns an UpdateChannel

Arguments
Name Description
id - ID! The ID of the update channel.

Example

Query
query updateChannel($id: ID!) {
  updateChannel(id: $id) {
    id
    name
    handle
    targetGroups {
      ...DeviceGroupFragment
    }
  }
}
Variables
{"id": 4}
Response
{
  "data": {
    "updateChannel": {
      "id": "4",
      "name": "xyz789",
      "handle": "xyz789",
      "targetGroups": [DeviceGroup]
    }
  }
}

updateChannels

Description

Fetches the list of all update channels.

Response

Returns [UpdateChannel!]!

Example

Query
query updateChannels {
  updateChannels {
    id
    name
    handle
    targetGroups {
      ...DeviceGroupFragment
    }
  }
}
Response
{
  "data": {
    "updateChannels": [
      {
        "id": 4,
        "name": "abc123",
        "handle": "abc123",
        "targetGroups": [DeviceGroup]
      }
    ]
  }
}

Mutations

createBaseImage

Description

Create a new base image in a base image collection.

Response

Returns a CreateBaseImagePayload

Arguments
Name Description
input - CreateBaseImageInput!

Example

Query
mutation createBaseImage($input: CreateBaseImageInput!) {
  createBaseImage(input: $input) {
    baseImage {
      ...BaseImageFragment
    }
  }
}
Variables
{"input": CreateBaseImageInput}
Response
{"data": {"createBaseImage": {"baseImage": BaseImage}}}

createBaseImageCollection

Description

Creates a new base image collection.

Arguments
Name Description
input - CreateBaseImageCollectionInput!

Example

Query
mutation createBaseImageCollection($input: CreateBaseImageCollectionInput!) {
  createBaseImageCollection(input: $input) {
    baseImageCollection {
      ...BaseImageCollectionFragment
    }
  }
}
Variables
{"input": CreateBaseImageCollectionInput}
Response
{
  "data": {
    "createBaseImageCollection": {
      "baseImageCollection": BaseImageCollection
    }
  }
}

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

createUpdateCampaign

Description

Creates a new update campaign.

Response

Returns a CreateUpdateCampaignPayload

Arguments
Name Description
input - CreateUpdateCampaignInput!

Example

Query
mutation createUpdateCampaign($input: CreateUpdateCampaignInput!) {
  createUpdateCampaign(input: $input) {
    updateCampaign {
      ...UpdateCampaignFragment
    }
  }
}
Variables
{"input": CreateUpdateCampaignInput}
Response
{
  "data": {
    "createUpdateCampaign": {
      "updateCampaign": UpdateCampaign
    }
  }
}

createUpdateChannel

Description

Creates a new update channel.

Response

Returns a CreateUpdateChannelPayload

Arguments
Name Description
input - CreateUpdateChannelInput!

Example

Query
mutation createUpdateChannel($input: CreateUpdateChannelInput!) {
  createUpdateChannel(input: $input) {
    updateChannel {
      ...UpdateChannelFragment
    }
  }
}
Variables
{"input": CreateUpdateChannelInput}
Response
{
  "data": {
    "createUpdateChannel": {
      "updateChannel": UpdateChannel
    }
  }
}

deleteBaseImage

Description

Deletes a base image.

Response

Returns a DeleteBaseImagePayload

Arguments
Name Description
input - DeleteBaseImageInput!

Example

Query
mutation deleteBaseImage($input: DeleteBaseImageInput!) {
  deleteBaseImage(input: $input) {
    baseImage {
      ...BaseImageFragment
    }
  }
}
Variables
{"input": DeleteBaseImageInput}
Response
{"data": {"deleteBaseImage": {"baseImage": BaseImage}}}

deleteBaseImageCollection

Description

Deletes a base image collection.

Arguments
Name Description
input - DeleteBaseImageCollectionInput!

Example

Query
mutation deleteBaseImageCollection($input: DeleteBaseImageCollectionInput!) {
  deleteBaseImageCollection(input: $input) {
    baseImageCollection {
      ...BaseImageCollectionFragment
    }
  }
}
Variables
{"input": DeleteBaseImageCollectionInput}
Response
{
  "data": {
    "deleteBaseImageCollection": {
      "baseImageCollection": BaseImageCollection
    }
  }
}

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

deleteUpdateChannel

Description

Deletes an update channel.

Response

Returns a DeleteUpdateChannelPayload

Arguments
Name Description
input - DeleteUpdateChannelInput!

Example

Query
mutation deleteUpdateChannel($input: DeleteUpdateChannelInput!) {
  deleteUpdateChannel(input: $input) {
    updateChannel {
      ...UpdateChannelFragment
    }
  }
}
Variables
{"input": DeleteUpdateChannelInput}
Response
{
  "data": {
    "deleteUpdateChannel": {
      "updateChannel": UpdateChannel
    }
  }
}

requestForwarderSession

Description

Requests a forwarder session for the specified device.

Response

Returns a RequestForwarderSessionPayload

Arguments
Name Description
input - RequestForwarderSessionInput!

Example

Query
mutation requestForwarderSession($input: RequestForwarderSessionInput!) {
  requestForwarderSession(input: $input) {
    sessionToken
  }
}
Variables
{"input": RequestForwarderSessionInput}
Response
{
  "data": {
    "requestForwarderSession": {
      "sessionToken": "abc123"
    }
  }
}

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"}}}

updateBaseImage

Description

Updates a base image.

Response

Returns an UpdateBaseImagePayload

Arguments
Name Description
input - UpdateBaseImageInput!

Example

Query
mutation updateBaseImage($input: UpdateBaseImageInput!) {
  updateBaseImage(input: $input) {
    baseImage {
      ...BaseImageFragment
    }
  }
}
Variables
{"input": UpdateBaseImageInput}
Response
{"data": {"updateBaseImage": {"baseImage": BaseImage}}}

updateBaseImageCollection

Description

Updates a base image collection.

Response

Returns an UpdateBaseImageCollectionPayload

Arguments
Name Description
input - UpdateBaseImageCollectionInput!

Example

Query
mutation updateBaseImageCollection($input: UpdateBaseImageCollectionInput!) {
  updateBaseImageCollection(input: $input) {
    baseImageCollection {
      ...BaseImageCollectionFragment
    }
  }
}
Variables
{"input": UpdateBaseImageCollectionInput}
Response
{
  "data": {
    "updateBaseImageCollection": {
      "baseImageCollection": BaseImageCollection
    }
  }
}

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

updateUpdateChannel

Description

Updates an update channel.

Response

Returns an UpdateUpdateChannelPayload

Arguments
Name Description
input - UpdateUpdateChannelInput!

Example

Query
mutation updateUpdateChannel($input: UpdateUpdateChannelInput!) {
  updateUpdateChannel(input: $input) {
    updateChannel {
      ...UpdateChannelFragment
    }
  }
}
Variables
{"input": UpdateUpdateChannelInput}
Response
{
  "data": {
    "updateUpdateChannel": {
      "updateChannel": UpdateChannel
    }
  }
}

Types

BaseImage

Description

Represents an uploaded Base Image.

A base image represents a downloadable base image that can be installed on a device

Fields
Field Name Description
id - ID! The ID of an object
version - String! The base image version
url - String! The url where the base image can be downloaded
startingVersionRequirement - String The starting version requirement for the base image
description - String The localized description of the base image 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.
releaseDisplayName - String The localized release display name of the base image 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.
baseImageCollection - BaseImageCollection! The Base Image Collection the Base Image belongs to
Example
{
  "id": "4",
  "version": "abc123",
  "url": "abc123",
  "startingVersionRequirement": "xyz789",
  "description": "xyz789",
  "releaseDisplayName": "abc123",
  "baseImageCollection": BaseImageCollection
}

BaseImageCollection

Description

Represents a collection of Base Images.

A base image collection represents the collection of all Base Images that can run on a specific System Model.

Fields
Field Name Description
id - ID! The ID of an object
name - String! The display name of the base image collection.
handle - String! The identifier of the base image collection.
systemModel - SystemModel The System Model associated with the Base Image Collection
baseImages - [BaseImage!]! The Base Images associated with the Base Image Collection
Example
{
  "id": "4",
  "name": "xyz789",
  "handle": "xyz789",
  "systemModel": SystemModel,
  "baseImages": [BaseImage]
}

BaseImageInfo

Description

Describes the information on the 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": "abc123",
  "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": 123.45,
  "levelAbsoluteError": 123.45,
  "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.

Example
true

CreateBaseImageCollectionInput

Fields
Input Field Description
name - String! The display name of the base image collection.
handle - String!

The identifier of the base image collection.

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

systemModelId - ID! The ID of the system model that is targeted by this base image collection
Example
{
  "name": "abc123",
  "handle": "abc123",
  "systemModelId": 4
}

CreateBaseImageCollectionPayload

Fields
Field Name Description
baseImageCollection - BaseImageCollection! The created base image collection.
Example
{"baseImageCollection": BaseImageCollection}

CreateBaseImageInput

Fields
Input Field Description
baseImageCollectionId - ID! The ID of the Base Image Collection this Base Image will belong to
version - String! The base image version
file - Upload! The base image file, which will be uploaded to the storage
startingVersionRequirement - String An optional starting version requirement for the base image
description - LocalizedTextInput An optional localized description. This description can currently only use the default tenant locale.
releaseDisplayName - LocalizedTextInput An optional relase display name. This can currently only use the default tenant locale.
Example
{
  "baseImageCollectionId": 4,
  "version": "abc123",
  "file": Upload,
  "startingVersionRequirement": "xyz789",
  "description": LocalizedTextInput,
  "releaseDisplayName": LocalizedTextInput
}

CreateBaseImagePayload

Fields
Field Name Description
baseImage - BaseImage! The created base image.
Example
{"baseImage": BaseImage}

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": "abc123",
  "handle": "abc123",
  "selector": "xyz789"
}

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": "abc123",
  "handle": "abc123",
  "partNumbers": ["abc123"]
}

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": "xyz789",
  "handle": "abc123",
  "pictureFile": Upload,
  "pictureUrl": "xyz789",
  "partNumbers": ["abc123"],
  "hardwareTypeId": 4,
  "description": LocalizedTextInput
}

CreateSystemModelPayload

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

CreateUpdateCampaignInput

Fields
Input Field Description
name - String! The name of the Update Campaign.
baseImageId - ID! The ID of the Base Image that will be distributed in the Update Campaign.
updateChannelId - ID! The ID of the Update Channel that will be targeted by the Update Campaign.
rolloutMechanism - RolloutMechanismInput! The Rollout Mechanism of the Update Campaign, with its properties
Example
{
  "name": "xyz789",
  "baseImageId": "4",
  "updateChannelId": "4",
  "rolloutMechanism": RolloutMechanismInput
}

CreateUpdateCampaignPayload

Fields
Field Name Description
updateCampaign - UpdateCampaign! The created Update Campaign.
Example
{"updateCampaign": UpdateCampaign}

CreateUpdateChannelInput

Fields
Input Field Description
name - String! The display name of the update channel.
handle - String!

The identifier of the update channel.

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

targetGroupIds - [ID!]! The IDs of the target groups that are targeted by this update channel
Example
{
  "name": "abc123",
  "handle": "abc123",
  "targetGroupIds": [4]
}

CreateUpdateChannelPayload

Fields
Field Name Description
updateChannel - UpdateChannel! The created update channel.
Example
{"updateChannel": UpdateChannel}

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"

DeleteBaseImageCollectionInput

Fields
Input Field Description
baseImageCollectionId - ID! The ID of the base image collection to be deleted.
Example
{"baseImageCollectionId": 4}

DeleteBaseImageCollectionPayload

Fields
Field Name Description
baseImageCollection - BaseImageCollection! The deleted base image collection.
Example
{"baseImageCollection": BaseImageCollection}

DeleteBaseImageInput

Fields
Input Field Description
baseImageId - ID! The ID of the base image to be deleted.
Example
{"baseImageId": "4"}

DeleteBaseImagePayload

Fields
Field Name Description
baseImage - BaseImage! The deleted base image.
Example
{"baseImage": BaseImage}

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}

DeleteUpdateChannelInput

Fields
Input Field Description
updateChannelId - ID! The ID of the update channel to be deleted.
Example
{"updateChannelId": 4}

DeleteUpdateChannelPayload

Fields
Field Name Description
updateChannel - UpdateChannel! The deleted update channel.
Example
{"updateChannel": UpdateChannel}

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 - BaseImageInfo 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.
networkInterfaces - [NetworkInterface!] The list of Network Interfaces of the device.
Example
{
  "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": BaseImageInfo,
  "osInfo": OsInfo,
  "otaOperations": [OtaOperation],
  "cellularConnection": [Modem],
  "runtimeInfo": RuntimeInfo,
  "networkInterfaces": [NetworkInterface]
}

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": "abc123",
  "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.

REMOTE_TERMINAL

The device can be geolocated.

GEOLOCATION

The device supports remote terminal sessions.

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": "xyz789",
  "hardwareTypeName": "xyz789",
  "tag": "xyz789"
}

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.
updateChannel - UpdateChannel The UpdateChannel associated with this group, if present.
Example
{
  "id": "4",
  "name": "xyz789",
  "handle": "abc123",
  "selector": "xyz789",
  "devices": [Device],
  "updateChannel": UpdateChannel
}

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": 987.65,
  "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
987.65

ForwarderConfig

Description

The details of a forwarder instance.

Fields
Field Name Description
hostname - String! The hostname of the forwarder instance.
port - Int! The port of the forwarder instance.
secureSessions - Boolean! Indicates if TLS should used when connecting to the forwarder.
Example
{
  "hostname": "xyz789",
  "port": 987,
  "secureSessions": false
}

ForwarderSession

Description

The details of a forwarder session

Fields
Field Name Description
token - String! The token that identifies the session.
status - ForwarderSessionStatus! The status of the session.
secure - Boolean! Indicates if TLS is used when the device connects to the forwarder.
forwarderHostname - String! The hostname of the forwarder instance.
forwarderPort - Int! The port of the forwarder instance.
Example
{
  "token": "abc123",
  "status": "CONNECTED",
  "secure": true,
  "forwarderHostname": "abc123",
  "forwarderPort": 123
}

ForwarderSessionStatus

Description

The status of a forwarder session

Values
Enum Value Description

CONNECTED

The device is connected to the forwarder.

CONNECTING

The device is connecting to the forwarder.
Example
"CONNECTED"

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": "xyz789",
  "cpuModel": "abc123",
  "cpuModelName": "xyz789",
  "cpuVendor": "xyz789",
  "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": "xyz789",
  "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
123

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"

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": "abc123",
  "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": "abc123",
  "imei": "abc123",
  "imsi": "xyz789",
  "carrier": "abc123",
  "cellId": 987,
  "mobileCountryCode": 987,
  "mobileNetworkCode": 987,
  "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"

NetworkInterface

Description

Describes a network interface of a device.

Fields
Field Name Description
name - String! The identifier of the network interface.
macAddress - String The normalized physical address.
technology - NetworkInterfaceTechnology Connection Technology
Example
{
  "name": "abc123",
  "macAddress": "xyz789",
  "technology": "ETHERNET"
}

NetworkInterfaceTechnology

Description

The connection technology of the network interface.

Values
Enum Value Description

ETHERNET

Ethernet.

BLUETOOTH

Bluetooth.

CELLULAR

Cellular.

WIFI

WiFi.
Example
"ETHERNET"

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
statusProgress - Int! The percentage progress [0-100] for the current status
statusCode - OtaOperationStatusCode The current status code of the operation
message - String A message with additional details about the current status
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": "xyz789",
  "status": "PENDING",
  "statusProgress": 123,
  "statusCode": "REQUEST_TIMEOUT",
  "message": "xyz789",
  "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

ACKNOWLEDGED

The OTA operation was acknowledged from the device

DOWNLOADING

The device is downloading the update

DEPLOYING

The device is deploying the update

DEPLOYED

The device deployed the update

REBOOTING

The device is in the process of rebooting

ERROR

A recoverable error happened during the OTA operation

FAILURE

The OTA operation ended with a failure. This is a final state of the OTA Operation

SUCCESS

The OTA operation ended successfully. This is a final state of the OTA Operation
Example
"PENDING"

OtaOperationStatusCode

Description

Status code of the OTA operation.

Values
Enum Value Description

REQUEST_TIMEOUT

The OTA Operation timed out while sending the request to the device

INVALID_REQUEST

The OTA Operation contained invalid data

UPDATE_ALREADY_IN_PROGRESS

An OTA Operation is already in progress on the device

NETWORK_ERROR

A network error was encountered

IO_ERROR

An IO error was encountered

INTERNAL_ERROR

An internal error was encountered

INVALID_BASE_IMAGE

The OTA Operation failed due to an invalid base image

SYSTEM_ROLLBACK

A system rollback has occurred

CANCELED

The OTA Operation was canceled
Example
"REQUEST_TIMEOUT"

PushRollout

Description

An object representing the properties of a Push Rollout Mechanism

Fields
Field Name Description
maxFailurePercentage - Float! The maximum percentage of failures allowed over the number of total targets. If the failures exceed this threshold, the Update Campaign terminates with a failure.
maxInProgressUpdates - Int! The maximum number of in progress updates. The Update Campaign will have at most this number of OTA Operations that are started but not yet finished (either successfully or not).
otaRequestRetries - Int! The number of attempts that have to be tried before giving up on the update of a specific target (and considering it an error). Note that the update is retried only if the OTA Request doesn't get acknowledged from the device.
otaRequestTimeoutSeconds - Int! The timeout (in seconds) Edgehog has to wait before considering an OTA Request lost (and possibly retry). It must be at least 30 seconds.
forceDowngrade - Boolean! This boolean flag determines if the Base Image will be pushed to the Device even if it already has a greater version of the Base Image.
Example
{
  "maxFailurePercentage": 123.45,
  "maxInProgressUpdates": 987,
  "otaRequestRetries": 123,
  "otaRequestTimeoutSeconds": 987,
  "forceDowngrade": true
}

PushRolloutInput

Description

An input object to set the properties of a Push Rollout Mechanism

Fields
Input Field Description
maxFailurePercentage - Float! The maximum percentage of failures allowed over the number of total targets. If the failures exceed this threshold, the Update Campaign terminates with a failure.
maxInProgressUpdates - Int! The maximum number of in progress updates. The Update Campaign will have at most this number of OTA Operations that are started but not yet finished (either successfully or not).
otaRequestRetries - Int

The number of attempts that have to be tried before giving up on the update of a specific target (and considering it an error). Note that the update is retried only if the OTA Request doesn't get acknowledged from the device.

Defaults to 0 if not present.

otaRequestTimeoutSeconds - Int

The timeout (in seconds) Edgehog has to wait before considering an OTA Request lost (and possibly retry).

Defaults to 60 seconds if not present.

forceDowngrade - Boolean

This boolean flag determines if the Base Image will be pushed to the Device even if it already has a greater version of the Base Image.

Defaults to false if not present.

Example
{
  "maxFailurePercentage": 987.65,
  "maxInProgressUpdates": 123,
  "otaRequestRetries": 123,
  "otaRequestTimeoutSeconds": 123,
  "forceDowngrade": false
}

RequestForwarderSessionInput

Fields
Input Field Description
deviceId - ID! The GraphQL ID of the device for the requested session.
Example
{"deviceId": "4"}

RequestForwarderSessionPayload

Fields
Field Name Description
sessionToken - String! The token of the requested forwarder session.
Example
{"sessionToken": "xyz789"}

RolloutMechanism

Description

A Rollout Mechanism used by an Update Campaign

Types
Union Types

PushRollout

Example
PushRollout

RolloutMechanismInput

Description

An input object to provide a Rollout Mechanism

Fields
Input Field Description
push - PushRolloutInput!
Example
{"push": PushRolloutInput}

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": "abc123",
  "environment": "xyz789",
  "url": "xyz789"
}

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": "xyz789",
  "totalBytes": 123,
  "freeBytes": 123
}

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
"abc123"

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 - String 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": "abc123"
}

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": "abc123",
  "memoryFreeBytes": 123,
  "taskCount": 987,
  "uptimeMilliseconds": 987,
  "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": "xyz789",
  "slug": "xyz789",
  "defaultLocale": "abc123"
}

UpdateBaseImageCollectionInput

Fields
Input Field Description
baseImageCollectionId - ID! The ID of the base image collection to be updated.
name - String The display name of the base image collection.
handle - String

The identifier of the base image collection.

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

Example
{
  "baseImageCollectionId": 4,
  "name": "abc123",
  "handle": "xyz789"
}

UpdateBaseImageCollectionPayload

Fields
Field Name Description
baseImageCollection - BaseImageCollection! The updated base image collection.
Example
{"baseImageCollection": BaseImageCollection}

UpdateBaseImageInput

Fields
Input Field Description
baseImageId - ID! The ID of the base image to be updated.
startingVersionRequirement - String The starting version requirement for the base image
description - LocalizedTextInput The localized description. This description can currently only use the default tenant locale.
releaseDisplayName - LocalizedTextInput The localized relase display name. This can currently only use the default tenant locale.
Example
{
  "baseImageId": 4,
  "startingVersionRequirement": "xyz789",
  "description": LocalizedTextInput,
  "releaseDisplayName": LocalizedTextInput
}

UpdateBaseImagePayload

Fields
Field Name Description
baseImage - BaseImage! The updated base image.
Example
{"baseImage": BaseImage}

UpdateCampaign

Description

Represents an UpdateCampaign.

An Update Campaign is the operation that tracks the distribution of a specific Base Image to all devices belonging to an Update Channel.

Fields
Field Name Description
id - ID! The ID of an object
name - String! The name of the Update Campaign.
status - UpdateCampaignStatus! The status of the Update Campaign.
outcome - UpdateCampaignOutcome The outcome of the Update Campaign, present only when it's finished.
rolloutMechanism - RolloutMechanism! The Rollout Mechanism used in the Update Campaign.
baseImage - BaseImage! The Base Image distributed in the Update Campaign.
updateChannel - UpdateChannel! The Update Channel targeted by the Update Campaign.
updateTargets - [UpdateTarget!]! The Targets that will receive the update during the Update Campaign.
stats - UpdateCampaignStats! The Stats of the Update Campaign
Example
{
  "id": 4,
  "name": "xyz789",
  "status": "IDLE",
  "outcome": "SUCCESS",
  "rolloutMechanism": PushRollout,
  "baseImage": BaseImage,
  "updateChannel": UpdateChannel,
  "updateTargets": [UpdateTarget],
  "stats": UpdateCampaignStats
}

UpdateCampaignOutcome

Description

The outcome of an Update Campaign

Values
Enum Value Description

SUCCESS

The Update Campaign has finished succesfully

FAILURE

The Update Campaign has finished with a failure
Example
"SUCCESS"

UpdateCampaignStats

Fields
Field Name Description
totalTargetCount - Int! The total number of targets of the Update Campaign
idleTargetCount - Int! The number of targets of the Update Campaign having IDLE status
inProgressTargetCount - Int! The number of targets of the Update Campaign having IN_PROGRESS status
failedTargetCount - Int! The number of targets of the Update Campaign having FAILED status
successfulTargetCount - Int! The number of targets of the Update Campaign having SUCCESSFUL status
Example
{
  "totalTargetCount": 123,
  "idleTargetCount": 123,
  "inProgressTargetCount": 987,
  "failedTargetCount": 987,
  "successfulTargetCount": 987
}

UpdateCampaignStatus

Description

The status of an Update Campaign

Values
Enum Value Description

IDLE

The Update Campaign has been created but is not being rolled-out yet

IN_PROGRESS

The Update Campaign is being rolled-out

FINISHED

The Update Campaign has finished
Example
"IDLE"

UpdateChannel

Description

Represents an UpdateChannel.

An UpdateChannel represents a set of TargetGroups that can be targeted in an UpdateCampaign

Fields
Field Name Description
id - ID! The ID of an object
name - String! The display name of the target group.
handle - String! The identifier of the target group.
targetGroups - [DeviceGroup!]! The DeviceGroups associated with this UpdateChannel
Example
{
  "id": "4",
  "name": "xyz789",
  "handle": "abc123",
  "targetGroups": [DeviceGroup]
}

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": "abc123"
}

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": "abc123",
  "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": "xyz789",
  "handle": "xyz789",
  "pictureFile": Upload,
  "pictureUrl": "abc123",
  "partNumbers": ["xyz789"],
  "description": LocalizedTextInput
}

UpdateSystemModelPayload

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

UpdateTarget

Description

Represents an UpdateTarget.

An Update Target is the target of an Update Campaign, which is composed by the targeted device and the status of the target in the linked Update Campaign.

Fields
Field Name Description
id - ID! The ID of an object
status - UpdateTargetStatus! The status of the Update Target.
retryCount - Int! The retry count of the Update Target. This indicates how many times Edgehog has tried to send an OTA Update towards the device without receiving an ack.
latestAttempt - DateTime The timestamp of the latest attempt to update the Update Target
completionTimestamp - DateTime The timestamp when the Update Target completed its update, either with a success or a failure
device - Device! The Target device.
otaOperation - OtaOperation The OTA Operation that tracks the Update Target in-progress update
Example
{
  "id": "4",
  "status": "IDLE",
  "retryCount": 123,
  "latestAttempt": "2007-12-03T10:15:30Z",
  "completionTimestamp": "2007-12-03T10:15:30Z",
  "device": Device,
  "otaOperation": OtaOperation
}

UpdateTargetStatus

Description

The status of an Update Target

Values
Enum Value Description

IDLE

The Update Campaign is waiting for the OTA Request to be sent

IN_PROGRESS

The Update Target is in progress

FAILED

The Update Target has failed to be updated

SUCCESSFUL

The Update Target was successfully updated
Example
"IDLE"

UpdateUpdateChannelInput

Fields
Input Field Description
updateChannelId - ID! The ID of the update channel to be updated
name - String The updated display name of the update channel.
handle - String

The updated identifier of the update channel.

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

targetGroupIds - [ID!] The updated IDs of the target groups that are targeted by this update channel
Example
{
  "updateChannelId": 4,
  "name": "xyz789",
  "handle": "xyz789",
  "targetGroupIds": [4]
}

UpdateUpdateChannelPayload

Fields
Field Name Description
updateChannel - UpdateChannel! The updated update channel.
Example
{"updateChannel": UpdateChannel}

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": "xyz789",
  "macAddress": "xyz789",
  "rssi": 123,
  "timestamp": "2007-12-03T10:15:30Z"
}