Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.
ReferenceBeta

Devices

Complete reference for devices: register GPS trackers and sensors, manage hardware identifiers, link devices to assets, and track relations.

Devices are GPS trackers, sensors, and other hardware that collect and transmit location and telemetry data.

Queries

deviceTypes

Lists device types in the caller's workspace.

deviceTypes(
    filter: CatalogItemFilter
    first: Int
    after: String
    last: Int
    before: String
    orderBy: CatalogItemOrder = { field: ORDER, direction: ASC }
  ): DeviceTypeConnection!

Arguments

Name
Type
Description

filter

CatalogItemFilter

Filtering options for the returned device types.

first

Int

The first n elements from the paginated list.

after

String

The elements that come after the specified cursor.

last

Int

The last n elements from the paginated list.

before

String

The elements that come before the specified cursor.

orderBy

CatalogItemOrder

The ordering options for the returned device types.

Input types:

CatalogItemFilter

Filtering options for catalog items.

Field
Type
Description

titleContains

String

Partial match on title (case-insensitive contains).

codes

[Code!]

Match any of these codes.

CatalogItemOrder

Ordering options for catalog items.

Field
Type
Description

field

The field to order by.

direction

The direction to order.

Output types:

DeviceTypeConnection

A paginated list of DeviceType items.

Implements: Connection

Field
Type
Description

edges

A list of edges.

nodes

A list of nodes in the connection (without edge metadata).

pageInfo

Information about the current page.

total

The total count of items matching the filter.


deviceStatuses

Lists device statuses in the caller's workspace.

Arguments

Name
Type
Description

filter

CatalogItemFilter

Filtering options for the returned device statuses.

first

Int

The first n elements from the paginated list.

after

String

The elements that come after the specified cursor.

last

Int

The last n elements from the paginated list.

before

String

The elements that come before the specified cursor.

orderBy

CatalogItemOrder

The ordering options for the returned device statuses.

Input types:

CatalogItemFilter

Filtering options for catalog items.

Field
Type
Description

titleContains

String

Partial match on title (case-insensitive contains).

codes

[Code!]

Match any of these codes.

CatalogItemOrder

Ordering options for catalog items.

Field
Type
Description

field

The field to order by.

direction

The direction to order.

Output types:

DeviceStatusConnection

A paginated list of DeviceStatus items.

Implements: Connection

Field
Type
Description

edges

A list of edges.

nodes

A list of nodes in the connection (without edge metadata).

pageInfo

Information about the current page.

total

The total count of items matching the filter.


deviceModels

Lists device models with optional vendor filter.

Arguments

Name
Type
Description

filter

DeviceModelFilter

Filtering options for the returned device models.

first

Int

The first n elements from the paginated list.

after

String

The elements that come after the specified cursor.

last

Int

The last n elements from the paginated list.

before

String

The elements that come before the specified cursor.

orderBy

CatalogItemOrder

The ordering options for the returned device models.

Input types:

DeviceModelFilter

Filtering options for device models.

Field
Type
Description

vendorIds

[ID!]

Filter by vendors (OR within field).

titleContains

String

Partial match on title (case-insensitive contains).

code

Exact code match.

supported

Boolean

Filter to models the platform supports (DeviceModel.supported).

CatalogItemOrder

Ordering options for catalog items.

Field
Type
Description

field

The field to order by.

direction

The direction to order.

Output types:

DeviceModelConnection

A paginated list of DeviceModel items.

Implements: Connection

Field
Type
Description

edges

A list of edges.

nodes

A list of nodes in the connection (without edge metadata).

pageInfo

Information about the current page.

total

The total count of items matching the filter.


deviceVendors

Lists device vendors in the caller's workspace.

Arguments

Name
Type
Description

filter

CatalogItemFilter

Filtering options for the returned device vendors.

first

Int

The first n elements from the paginated list.

after

String

The elements that come after the specified cursor.

last

Int

The last n elements from the paginated list.

before

String

The elements that come before the specified cursor.

orderBy

CatalogItemOrder

The ordering options for the returned device vendors.

Input types:

CatalogItemFilter

Filtering options for catalog items.

Field
Type
Description

titleContains

String

Partial match on title (case-insensitive contains).

codes

[Code!]

Match any of these codes.

CatalogItemOrder

Ordering options for catalog items.

Field
Type
Description

field

The field to order by.

direction

The direction to order.

Output types:

DeviceVendorConnection

A paginated list of DeviceVendor items.

Implements: Connection

Field
Type
Description

edges

A list of edges.

nodes

A list of nodes in the connection (without edge metadata).

pageInfo

Information about the current page.

total

The total count of items matching the filter.


deviceRelationTypes

Lists device relation types in the caller's workspace.

Arguments

Name
Type
Description

filter

CatalogItemFilter

Filtering options for the returned device relation types.

first

Int

The first n elements from the paginated list.

after

String

The elements that come after the specified cursor.

last

Int

The last n elements from the paginated list.

before

String

The elements that come before the specified cursor.

orderBy

CatalogItemOrder

The ordering options for the returned device relation types.

Input types:

CatalogItemFilter

Filtering options for catalog items.

Field
Type
Description

titleContains

String

Partial match on title (case-insensitive contains).

codes

[Code!]

Match any of these codes.

CatalogItemOrder

Ordering options for catalog items.

Field
Type
Description

field

The field to order by.

direction

The direction to order.

Output types:

DeviceRelationTypeConnection

A paginated list of DeviceRelationType items.

Implements: Connection

Field
Type
Description

edges

A list of edges.

nodes

A list of nodes in the connection (without edge metadata).

pageInfo

Information about the current page.

total

The total count of items matching the filter.


device (query)

Retrieves a device by its ID.

Arguments

Name
Type
Description

id

ID!

The ID of the device to retrieve.

Output types:

Device

A tracking device such as a GPS tracker, sensor, or beacon.

Implements: Node, Titled, Versioned, InventoryItem

Field
Type
Description

id

ID!

A globally unique identifier. This ID is opaque and should not be parsed by clients.

version

Int!

The version number for optimistic locking. Incremented on each update. Can be provided in update/delete mutations to prevent lost updates. If omitted, the update proceeds without stale-read protection.

title

String!

The human-readable display name.

workspace

The workspace that owns this device.

type

The device type classification.

model

The specific device model.

status

The current operational status.

createdAt

When this device record was created.

activation

SIM/APN activation data, present once the device has gone through deviceActivate. Null for a device created only via deviceCreate. Also null, with an INTERNAL_ERROR on this field alone, for a stored activation the server cannot read, such as one with a missing key; the device itself and the list it is in are served.

identifiers

The hardware identifiers for this device (IMEI, serial number, MAC address, etc.).

asset

The asset this device is currently linked to.

inventory

The inventory this device is currently assigned to.

relationsFrom

The outgoing relationships from this device to other devices.

relationsTo

The incoming relationships from other devices to this device.

inventoryHistory

The history of inventory assignments for this device.


devices

Lists devices in the caller's workspace.

Arguments

Name
Type
Description

filter

DeviceFilter

Filtering options for the returned devices.

first

Int

The first n elements from the paginated list.

after

String

The elements that come after the specified cursor.

last

Int

The last n elements from the paginated list.

before

String

The elements that come before the specified cursor.

orderBy

DeviceOrder

The ordering options for the returned devices.

Input types:

DeviceFilter

Filtering options for devices.

Field
Type
Description

typeIds

[ID!]

Filter by device types (OR within field).

modelIds

[ID!]

Filter by device models (OR within field).

statusIds

[ID!]

Filter by statuses (OR within field).

vendorIds

[ID!]

Filter by vendors (OR within field).

identifierContains

String

Partial match on device identifier value (case-insensitive contains).

inventoryIds

[ID!]

Filter by inventories (OR within field).

titleContains

String

Partial match on title (case-insensitive contains).

search

String

Free-text search for a device list search box: a device matches when its title or any of its identifier values contains the value (case-insensitive), or its activation SIM phone number contains it. The phone is stored as digits only, so spaces and the characters +, -, (, ) and . are dropped from the value before it is compared with the phone. So 866104 finds a device by IMEI or by phone, and +49 151 by phone. A value of only those characters still matches by title and identifier.

DeviceOrder

Ordering options for devices.

Field
Type
Description

field

The field to order by.

direction

The direction to order.

Output types:

DeviceConnection

A paginated list of Device items.

Implements: Connection

Field
Type
Description

edges

A list of edges.

nodes

[Device!]!

A list of nodes in the connection (without edge metadata).

pageInfo

Information about the current page.

total

The total count of items matching the filter.


deviceActivationServer

The data gateway address a device of this model is pointed at: what the user enters on the device for MANUAL setup, before deviceActivate, and what the Register SMS carries for AUTOMATIC. The port is that of the model's protocol. Null while the installation publishes no address. Refused for a model that is not supported, as deviceActivate is. Needs the create right on devices.

Arguments

Name
Type
Description

modelId

ID!

The device model the device is activated with. Must be supported.

Output types:

ActivationServerAddress

The data gateway address a device connects to.

Field
Type
Description

host

String!

The host name or IP address.

port

Int!

The TCP port.


deviceActivationPhoneAvailable

Whether deviceActivate would accept this phone: no device of any workspace holds it, or the one that does is the caller's device with identifier. Lets a client check the phone before submitting the form; deviceActivate still enforces uniqueness, so a phone taken in between is refused there with DUPLICATE.

Arguments

Name
Type
Description

phone

String!

The SIM phone number, as DeviceActivateInput.phone takes it: 5 to 20 digits.

identifier

String

The identifier the form activates, as DeviceActivateInput.identifier takes it. The phone of the caller's device with this identifier counts as available, since re-running activation for that device keeps it.


Mutations

deviceCreate

Creates a new device.

Arguments

Name
Type
Description

input

DeviceCreateInput!

The input fields for creating the device.

Input types:

DeviceCreateInput

Input for creating a new device.

Field
Type
Description

typeId

ID!

The device type ID.

modelId

ID!

The device model ID.

title

String

The device display name. If omitted or blank, the server generates "<vendor.title> <model.title> <identifier.value>" where the identifier is chosen by type priority: IMEI > SERIAL_NUMBER > MAC_ADDRESS, with fallback to identifiers[0] when none of the priority types are present. With no identifiers at all the generated title is "<vendor.title> <model.title>".

identifiers

The hardware identifiers. Optional: a device may be registered before its hardware is known. Identifiers can be added later with deviceIdentifierAdd.

inventoryId

ID

Optionally assign the new device to an existing inventory. When provided, the inventory must belong to the same workspace; the assignment is atomic with device creation (the device is not created if the assignment fails).

DeviceIdentifierInput

Input for a device identifier.

Field
Type
Description

type

The type of identifier.

value

String!

The identifier value. 1 to 64 Unicode code points, measured after @trim has removed leading and trailing whitespace. An astral character such as an emoji counts as one, though a UTF-16 length reports it as two. The limit is not expressible in the schema and is enforced by the server: a longer value is rejected with VALIDATION_ERROR.

namespace

The namespace for uniqueness scope. Null means globally unique.

Output types:

DevicePayload

The result of a device mutation.

Field
Type
Description

device

The created or updated device.

Device (entity)

A tracking device such as a GPS tracker, sensor, or beacon.

Implements: Node, Titled, Versioned, InventoryItem

Field
Type
Description

id

ID!

A globally unique identifier. This ID is opaque and should not be parsed by clients.

version

Int!

The version number for optimistic locking. Incremented on each update. Can be provided in update/delete mutations to prevent lost updates. If omitted, the update proceeds without stale-read protection.

title

String!

The human-readable display name.

workspace

The workspace that owns this device.

type

The device type classification.

model

The specific device model.

status

The current operational status.

createdAt

When this device record was created.

activation

SIM/APN activation data, present once the device has gone through deviceActivate. Null for a device created only via deviceCreate. Also null, with an INTERNAL_ERROR on this field alone, for a stored activation the server cannot read, such as one with a missing key; the device itself and the list it is in are served.

identifiers

The hardware identifiers for this device (IMEI, serial number, MAC address, etc.).

asset

The asset this device is currently linked to.

inventory

The inventory this device is currently assigned to.

relationsFrom

The outgoing relationships from this device to other devices.

relationsTo

The incoming relationships from other devices to this device.

inventoryHistory

The history of inventory assignments for this device.


deviceUpdate

Updates an existing device.

Arguments

Name
Type
Description

input

DeviceUpdateInput!

The input fields for updating the device.

Input types:

DeviceUpdateInput

Input for updating an existing device.

Field
Type
Description

id

ID!

The device ID to update.

version

Int

The current version for optimistic locking. If omitted, auto-increments without conflict check.

modelId

ID

The new device model.

title

String

The new display name.

Output types:

DevicePayload

The result of a device mutation.

Field
Type
Description

device

The created or updated device.

Device (entity)

A tracking device such as a GPS tracker, sensor, or beacon.

Implements: Node, Titled, Versioned, InventoryItem

Field
Type
Description

id

ID!

A globally unique identifier. This ID is opaque and should not be parsed by clients.

version

Int!

The version number for optimistic locking. Incremented on each update. Can be provided in update/delete mutations to prevent lost updates. If omitted, the update proceeds without stale-read protection.

title

String!

The human-readable display name.

workspace

The workspace that owns this device.

type

The device type classification.

model

The specific device model.

status

The current operational status.

createdAt

When this device record was created.

activation

SIM/APN activation data, present once the device has gone through deviceActivate. Null for a device created only via deviceCreate. Also null, with an INTERNAL_ERROR on this field alone, for a stored activation the server cannot read, such as one with a missing key; the device itself and the list it is in are served.

identifiers

The hardware identifiers for this device (IMEI, serial number, MAC address, etc.).

asset

The asset this device is currently linked to.

inventory

The inventory this device is currently assigned to.

relationsFrom

The outgoing relationships from this device to other devices.

relationsTo

The incoming relationships from other devices to this device.

inventoryHistory

The history of inventory assignments for this device.


deviceDelete

Deletes a device.

Every DEVICE custom-field value pointing at it is detached in the same transaction, on assets and on geo objects alike, so no holder is left naming a device that is gone. A value in a field that isRequired is not detached, since that would leave its holder invalid; it refuses the delete instead.

Refused with IN_USE while another live entity points at it through one of its own fields, custom-field values and field definitions included; the error's blockers name the first five of them, and hasMoreBlockers says whether it left any out. A required DEVICE field holding the device and a live flow linking it, in a workspace that has IoT Logic, are among them; the flows of a workspace without IoT Logic block nothing. Nothing is detached when the delete is refused.

Arguments

Name
Type
Description

input

DeviceDeleteInput!

The input fields for deleting the device.

Input types:

DeviceDeleteInput

Input for deleting a device.

Field
Type
Description

id

ID!

The device ID to delete.

version

Int

The current version for optimistic locking. If omitted, auto-increments without conflict check.

Output types:

DeletePayload

The result of a delete mutation.

Field
Type
Description

deletedId

ID!

The ID of the deleted entity.


deviceIdentifierAdd

Adds an identifier to a device.

Not an idempotent command: DUPLICATE when an identifier with the same type, value and namespace already exists — the uniqueness scope is the whole installation, not the device, so the conflict may sit on a device the caller cannot see. A null namespace is global and collides with other null namespaces.

Arguments

Name
Type
Description

input

DeviceIdentifierAddInput!

The input fields for adding the identifier.

Input types:

DeviceIdentifierAddInput

Input for adding an identifier to a device.

Field
Type
Description

deviceId

ID!

The device ID.

identifier

The identifier details.

DeviceIdentifierInput

Input for a device identifier.

Field
Type
Description

type

The type of identifier.

value

String!

The identifier value. 1 to 64 Unicode code points, measured after @trim has removed leading and trailing whitespace. An astral character such as an emoji counts as one, though a UTF-16 length reports it as two. The limit is not expressible in the schema and is enforced by the server: a longer value is rejected with VALIDATION_ERROR.

namespace

The namespace for uniqueness scope. Null means globally unique.

Output types:

DeviceIdentifierPayload

The result of a device identifier mutation.

Field
Type
Description

deviceIdentifier

The added device identifier.

DeviceIdentifier (entity)

A hardware identifier for a device.

Implements: Node

Field
Type
Description

id

ID!

A globally unique identifier. This ID is opaque and should not be parsed by clients.

device

The device this identifier belongs to.

type

The type of identifier.

value

String!

The identifier value.

namespace

The namespace for uniqueness scope. Null means the identifier is globally unique.


deviceIdentifierRemove

Removes an identifier from a device.

Not an idempotent command: NOT_FOUND when identifierId names no identifier, including a repeat of a call that already succeeded.

Arguments

Name
Type
Description

input

DeviceIdentifierRemoveInput!

The input fields for removing the identifier.

Input types:

DeviceIdentifierRemoveInput

Input for removing an identifier from a device.

Field
Type
Description

identifierId

ID!

The identifier ID to remove.

Output types:

DeletePayload

The result of a delete mutation.

Field
Type
Description

deletedId

ID!

The ID of the deleted entity.


deviceActivate

Activates a device: creates it with the given identifier, records SIM/APN data and sets it awaiting_connection. For AUTOMATIC setup it also queues the SMS with APN and server settings; for MANUAL setup nothing is sent, and the user enters DeviceActivation.server on the device. The first frame makes it active. For an IMEI already on a not_activated or awaiting_connection device of the caller's workspace, replaces that device's activation data and model, cancels an SMS of its previous activation still waiting to be sent and, for AUTOMATIC setup, queues the SMS again; an active or inactive device is refused. A serial number already on any device is refused as DUPLICATE, whatever its status. The device is returned even when the SMS could not be queued, and activationSms says whether it was.

Arguments

Name
Type
Description

input

DeviceActivateInput!

The input fields for activating the device.

Input types:

DeviceActivateInput

Input for activating a device: creates it with the given identifier, records SIM/APN data, sets it awaiting_connection, and for AUTOMATIC setup queues the SMS that pushes APN and server settings to it.

Field
Type
Description

setup

How the device receives its server settings.

modelId

ID!

The device model. Must be supported.

title

String

The device display name. For a new device, <model title> <identifier> when omitted or blank. For an existing device this activation attaches to, replaces its title when given and keeps it when omitted or blank.

identifier

String!

The identifier the model's protocol names a device by: the IMEI (15 digits) for most models, the serial number (6 to 10 digits, not all zeros, leading zeros kept) for Suntech models. Becomes the device's IMEI or SERIAL_NUMBER identifier, the serial number in the namespace of its protocol (suntech). Checked against the model: VALIDATION_ERROR on identifier otherwise.

phone

String

The SIM phone number the activation SMS is sent to: 5 to 20 digits, globally unique across the installation. Required for AUTOMATIC setup, optional for MANUAL.

apn

The APN settings pushed to the device. Required for AUTOMATIC setup, optional for MANUAL.

ApnSettingsInput

APN settings for deviceActivate.

Field
Type
Description

name

String!

The APN name: 1-40 characters of letters, digits, ., _ or -.

user

String

The APN username, if the carrier requires one: at most 40 characters of letters, digits, ., _, - or @.

password

String

The APN password, if the carrier requires one: at most 40 characters of letters, digits, ., _, - or @. Not saved in the device activation: it goes only into the activation SMS text, which the command queue keeps with the queued command. Ignored for MANUAL setup.

Output types:

DeviceActivatePayload

The result of deviceActivate.

Field
Type
Description

device

The activated device.

activationSms

Whether the activation SMS was queued, for AUTOMATIC setup. Null for MANUAL setup, which sends no SMS.

Device (entity)

A tracking device such as a GPS tracker, sensor, or beacon.

Implements: Node, Titled, Versioned, InventoryItem

Field
Type
Description

id

ID!

A globally unique identifier. This ID is opaque and should not be parsed by clients.

version

Int!

The version number for optimistic locking. Incremented on each update. Can be provided in update/delete mutations to prevent lost updates. If omitted, the update proceeds without stale-read protection.

title

String!

The human-readable display name.

workspace

The workspace that owns this device.

type

The device type classification.

model

The specific device model.

status

The current operational status.

createdAt

When this device record was created.

activation

SIM/APN activation data, present once the device has gone through deviceActivate. Null for a device created only via deviceCreate. Also null, with an INTERNAL_ERROR on this field alone, for a stored activation the server cannot read, such as one with a missing key; the device itself and the list it is in are served.

identifiers

The hardware identifiers for this device (IMEI, serial number, MAC address, etc.).

asset

The asset this device is currently linked to.

inventory

The inventory this device is currently assigned to.

relationsFrom

The outgoing relationships from this device to other devices.

relationsTo

The incoming relationships from other devices to this device.

inventoryHistory

The history of inventory assignments for this device.


deviceRelationCreate

Creates a relationship between devices.

Not an idempotent command: DUPLICATE when the same firstId, secondId and typeId are already related. The pair is ordered — relating A to B does not relate B to A, and creating the reverse is a second, separate relationship rather than a duplicate.

Arguments

Name
Type
Description

input

DeviceRelationCreateInput!

The input fields for creating the relationship.

Input types:

DeviceRelationCreateInput

Input for creating a relationship between devices.

Field
Type
Description

firstId

ID!

The first device ID.

secondId

ID!

The second device ID.

typeId

ID!

The relationship type ID.

Output types:

DeviceRelationPayload

The result of a device relation mutation.

Field
Type
Description

deviceRelation

The created device relationship.

DeviceRelation (entity)

A relationship between two devices.

Implements: Node

Field
Type
Description

id

ID!

A globally unique identifier. This ID is opaque and should not be parsed by clients.

first

The first device in the relationship.

second

The second device in the relationship.

type

The type of relationship.


deviceRelationRemove

Removes a device relationship.

Not an idempotent command: NOT_FOUND when id names no relationship, including a repeat of a call that already succeeded.

Arguments

Name
Type
Description

input

DeviceRelationRemoveInput!

The input fields for removing the relationship.

Input types:

DeviceRelationRemoveInput

Input for removing a device relationship.

Field
Type
Description

id

ID!

The relationship ID to remove.

Output types:

DeletePayload

The result of a delete mutation.

Field
Type
Description

deletedId

ID!

The ID of the deleted entity.


deviceTypeCreate

Creates a new device type.

Arguments

Name
Type
Description

input

DeviceTypeCreateInput!

The input fields for creating the device type.

Input types:

DeviceTypeCreateInput

Input for creating a device type.

Field
Type
Description

code

The machine-readable code. Auto-generated from title if omitted.

title

String!

The display name.

order

Int

The display order. Auto-calculated as last position if omitted.

meta

The display properties.

CatalogItemMetaInput

Display properties for catalog items.

Field
Type
Description

description

String

The description.

hidden

Boolean

Whether the item is hidden from regular UI lists.

Output types:

DeviceTypePayload

The result of a device type mutation.

Field
Type
Description

deviceType

The created or updated device type.

DeviceType (entity)

A classification type for devices.

Implements: CatalogItem, Node, Versioned, Titled

Field
Type
Description

id

ID!

A globally unique identifier.

version

Int!

The version number for optimistic locking.

title

String!

The human-readable display name. Can be localized.

code

A machine-readable code, unique within the catalog for a given workspace. A workspace item may reuse the code of the system item it overrides.

order

Int!

The display order within the same level or category.

catalog

The catalog this item belongs to.

workspace

The workspace that owns this item. Null for system items.

meta

Metadata about this item including description, origin, and display properties.


deviceTypeUpdate

Updates a device type.

Arguments

Name
Type
Description

input

DeviceTypeUpdateInput!

The input fields for updating the device type.

Input types:

DeviceTypeUpdateInput

Input for updating a device type.

Field
Type
Description

id

ID!

The item ID to update.

version

Int

The current version for optimistic locking. If omitted, auto-increments without conflict check.

title

String

The new display name.

order

Int

The new display order.

meta

The display properties.

CatalogItemMetaInput

Display properties for catalog items.

Field
Type
Description

description

String

The description.

hidden

Boolean

Whether the item is hidden from regular UI lists.

Output types:

DeviceTypePayload

The result of a device type mutation.

Field
Type
Description

deviceType

The created or updated device type.

DeviceType (entity)

A classification type for devices.

Implements: CatalogItem, Node, Versioned, Titled

Field
Type
Description

id

ID!

A globally unique identifier.

version

Int!

The version number for optimistic locking.

title

String!

The human-readable display name. Can be localized.

code

A machine-readable code, unique within the catalog for a given workspace. A workspace item may reuse the code of the system item it overrides.

order

Int!

The display order within the same level or category.

catalog

The catalog this item belongs to.

workspace

The workspace that owns this item. Null for system items.

meta

Metadata about this item including description, origin, and display properties.


deviceTypeDelete

Deletes a device type.

Refused with IN_USE while another live entity points at it through one of its own fields, custom-field values and field definitions included; the error's blockers name the first five of them, and hasMoreBlockers says whether it left any out.

Arguments

Name
Type
Description

input

CatalogItemDeleteInput!

The input fields for deleting the device type.

Input types:

CatalogItemDeleteInput

Input for deleting a catalog item.

Field
Type
Description

id

ID!

The catalog item ID to delete.

version

Int

The current version for optimistic locking. If omitted, auto-increments without conflict check.

Output types:

DeletePayload

The result of a delete mutation.

Field
Type
Description

deletedId

ID!

The ID of the deleted entity.


deviceStatusCreate

Creates a new device status.

Arguments

Name
Type
Description

input

DeviceStatusCreateInput!

The input fields for creating the device status.

Input types:

DeviceStatusCreateInput

Input for creating a device status.

Field
Type
Description

code

The machine-readable code. Auto-generated from title if omitted.

title

String!

The display name.

order

Int

The display order. Auto-calculated as last position if omitted.

meta

The display properties.

CatalogItemMetaInput

Display properties for catalog items.

Field
Type
Description

description

String

The description.

hidden

Boolean

Whether the item is hidden from regular UI lists.

Output types:

DeviceStatusPayload

The result of a device status mutation.

Field
Type
Description

deviceStatus

The created or updated device status.

DeviceStatus (entity)

An operational status for devices.

Implements: CatalogItem, Node, Versioned, Titled

Field
Type
Description

id

ID!

A globally unique identifier.

version

Int!

The version number for optimistic locking.

title

String!

The human-readable display name. Can be localized.

code

A machine-readable code, unique within the catalog for a given workspace. A workspace item may reuse the code of the system item it overrides.

order

Int!

The display order within the same level or category.

catalog

The catalog this item belongs to.

workspace

The workspace that owns this item. Null for system items.

meta

Metadata about this item including description, origin, and display properties.


deviceStatusUpdate

Updates a device status.

Arguments

Name
Type
Description

input

DeviceStatusUpdateInput!

The input fields for updating the device status.

Input types:

DeviceStatusUpdateInput

Input for updating a device status.

Field
Type
Description

id

ID!

The item ID to update.

version

Int

The current version for optimistic locking. If omitted, auto-increments without conflict check.

title

String

The new display name.

order

Int

The new display order.

meta

The display properties.

CatalogItemMetaInput

Display properties for catalog items.

Field
Type
Description

description

String

The description.

hidden

Boolean

Whether the item is hidden from regular UI lists.

Output types:

DeviceStatusPayload

The result of a device status mutation.

Field
Type
Description

deviceStatus

The created or updated device status.

DeviceStatus (entity)

An operational status for devices.

Implements: CatalogItem, Node, Versioned, Titled

Field
Type
Description

id

ID!

A globally unique identifier.

version

Int!

The version number for optimistic locking.

title

String!

The human-readable display name. Can be localized.

code

A machine-readable code, unique within the catalog for a given workspace. A workspace item may reuse the code of the system item it overrides.

order

Int!

The display order within the same level or category.

catalog

The catalog this item belongs to.

workspace

The workspace that owns this item. Null for system items.

meta

Metadata about this item including description, origin, and display properties.


deviceStatusDelete

Deletes a device status.

Refused with IN_USE while another live entity points at it through one of its own fields, custom-field values and field definitions included; the error's blockers name the first five of them, and hasMoreBlockers says whether it left any out.

Arguments

Name
Type
Description

input

CatalogItemDeleteInput!

The input fields for deleting the device status.

Input types:

CatalogItemDeleteInput

Input for deleting a catalog item.

Field
Type
Description

id

ID!

The catalog item ID to delete.

version

Int

The current version for optimistic locking. If omitted, auto-increments without conflict check.

Output types:

DeletePayload

The result of a delete mutation.

Field
Type
Description

deletedId

ID!

The ID of the deleted entity.


Objects

DeviceVendor

A device manufacturer or vendor.

Implements: CatalogItem, Node, Versioned, Titled

Field
Type
Description

id

ID!

A globally unique identifier.

version

Int!

The version number for optimistic locking.

title

String!

The human-readable display name. Can be localized.

code

A machine-readable code, unique within the catalog for a given workspace. A workspace item may reuse the code of the system item it overrides.

order

Int!

The display order within the same level or category.

catalog

The catalog this item belongs to.

workspace

The workspace that owns this item. Null for system items.

meta

Metadata about this item including description, origin, and display properties.

models

Device models produced by this vendor.

Arguments of models

Name
Type
Description

filter

Filtering options for the returned models.

first

Int

The first n elements from the paginated list.

after

String

The elements that come after the specified cursor.

last

Int

The last n elements from the paginated list.

before

String

The elements that come before the specified cursor.

orderBy

The ordering options for the returned models. Default: { field: TITLE, direction: ASC }.


DeviceModel

A specific device model produced by a vendor.

Implements: CatalogItem, Node, Versioned, Titled

Field
Type
Description

id

ID!

A globally unique identifier.

version

Int!

The version number for optimistic locking.

title

String!

The human-readable display name. Can be localized.

code

A machine-readable code, unique within the catalog for a given workspace. A workspace item may reuse the code of the system item it overrides.

order

Int!

The display order within the same level or category.

catalog

The catalog this item belongs to.

workspace

The workspace that owns this item. Null for system items.

meta

Metadata about this item including description, origin, and display properties.

vendor

The vendor that manufactures this model.

supported

Boolean!

Whether the platform decodes this model's data.


DeviceType

A classification type for devices.

Implements: CatalogItem, Node, Versioned, Titled

Field
Type
Description

id

ID!

A globally unique identifier.

version

Int!

The version number for optimistic locking.

title

String!

The human-readable display name. Can be localized.

code

A machine-readable code, unique within the catalog for a given workspace. A workspace item may reuse the code of the system item it overrides.

order

Int!

The display order within the same level or category.

catalog

The catalog this item belongs to.

workspace

The workspace that owns this item. Null for system items.

meta

Metadata about this item including description, origin, and display properties.


DeviceStatus

An operational status for devices.

Implements: CatalogItem, Node, Versioned, Titled

Field
Type
Description

id

ID!

A globally unique identifier.

version

Int!

The version number for optimistic locking.

title

String!

The human-readable display name. Can be localized.

code

A machine-readable code, unique within the catalog for a given workspace. A workspace item may reuse the code of the system item it overrides.

order

Int!

The display order within the same level or category.

catalog

The catalog this item belongs to.

workspace

The workspace that owns this item. Null for system items.

meta

Metadata about this item including description, origin, and display properties.


DeviceRelationType

A type of relationship between two devices.

Implements: CatalogItem, Node, Versioned, Titled

Field
Type
Description

id

ID!

A globally unique identifier.

version

Int!

The version number for optimistic locking.

title

String!

The human-readable display name. Can be localized.

code

A machine-readable code, unique within the catalog for a given workspace. A workspace item may reuse the code of the system item it overrides.

order

Int!

The display order within the same level or category.

catalog

The catalog this item belongs to.

workspace

The workspace that owns this item. Null for system items.

meta

Metadata about this item including description, origin, and display properties.


Device

A tracking device such as a GPS tracker, sensor, or beacon.

Implements: Node, Titled, Versioned, InventoryItem

Field
Type
Description

id

ID!

A globally unique identifier. This ID is opaque and should not be parsed by clients.

version

Int!

The version number for optimistic locking. Incremented on each update. Can be provided in update/delete mutations to prevent lost updates. If omitted, the update proceeds without stale-read protection.

title

String!

The human-readable display name.

workspace

The workspace that owns this device.

type

The device type classification.

model

The specific device model.

status

The current operational status.

createdAt

When this device record was created.

activation

SIM/APN activation data, present once the device has gone through deviceActivate. Null for a device created only via deviceCreate. Also null, with an INTERNAL_ERROR on this field alone, for a stored activation the server cannot read, such as one with a missing key; the device itself and the list it is in are served.

identifiers

The hardware identifiers for this device (IMEI, serial number, MAC address, etc.).

asset

The asset this device is currently linked to.

inventory

The inventory this device is currently assigned to.

relationsFrom

The outgoing relationships from this device to other devices.

relationsTo

The incoming relationships from other devices to this device.

inventoryHistory

The history of inventory assignments for this device.

Arguments of inventoryHistory

Name
Type
Description

first

Int

The first n elements from the paginated list.

after

String

The elements that come after the specified cursor.

last

Int

The last n elements from the paginated list.

before

String

The elements that come before the specified cursor.

orderBy

The ordering options for the returned history. Default: { field: ASSIGNED_AT direction: DESC }.


DeviceActivation

SIM/APN data recorded by deviceActivate; for AUTOMATIC setup, the Register SMS the platform sends to the device is built from it. Present once activation has run; absent for a device created only via deviceCreate. Whether the device has connected since is its status: awaiting_connection until its first frame reaches the platform, active after.

Field
Type
Description

setup

How the device receives its server settings.

phone

String

The SIM phone number, globally unique across the installation. The activation SMS is sent to it for AUTOMATIC setup. Null for MANUAL setup activated without one.

apn

The APN settings, pushed to the device for AUTOMATIC setup. Null for MANUAL setup activated without them.

server

The data gateway address the device connects to, to be entered on the device for MANUAL setup. The port is that of the protocol of the device's model, and follows the model when it changes. Null while the installation publishes no address, and for a device whose model has no protocol the gateway knows.

activatedAt

When deviceActivate last recorded this activation.


ActivationServerAddress

The data gateway address a device connects to.

Field
Type
Description

host

String!

The host name or IP address.

port

Int!

The TCP port.


ApnSettings

APN (Access Point Name) settings pushed to a device by the Register command.

Field
Type
Description

name

String!

The APN name.

user

String

The APN username, if the carrier requires one.


DeviceIdentifier

A hardware identifier for a device.

Implements: Node

Field
Type
Description

id

ID!

A globally unique identifier. This ID is opaque and should not be parsed by clients.

device

The device this identifier belongs to.

type

The type of identifier.

value

String!

The identifier value.

namespace

The namespace for uniqueness scope. Null means the identifier is globally unique.


DeviceRelation

A relationship between two devices.

Implements: Node

Field
Type
Description

id

ID!

A globally unique identifier. This ID is opaque and should not be parsed by clients.

first

The first device in the relationship.

second

The second device in the relationship.

type

The type of relationship.


DevicePayload

The result of a device mutation.

Field
Type
Description

device

The created or updated device.


DeviceActivatePayload

The result of deviceActivate.

Field
Type
Description

device

The activated device.

activationSms

Whether the activation SMS was queued, for AUTOMATIC setup. Null for MANUAL setup, which sends no SMS.


DeviceIdentifierPayload

The result of a device identifier mutation.

Field
Type
Description

deviceIdentifier

The added device identifier.


DeviceRelationPayload

The result of a device relation mutation.

Field
Type
Description

deviceRelation

The created device relationship.


DeviceTypePayload

The result of a device type mutation.

Field
Type
Description

deviceType

The created or updated device type.


DeviceStatusPayload

The result of a device status mutation.

Field
Type
Description

deviceStatus

The created or updated device status.


Inputs

DeviceFilter

Filtering options for devices.

Field
Type
Description

typeIds

[ID!]

Filter by device types (OR within field).

modelIds

[ID!]

Filter by device models (OR within field).

statusIds

[ID!]

Filter by statuses (OR within field).

vendorIds

[ID!]

Filter by vendors (OR within field).

identifierContains

String

Partial match on device identifier value (case-insensitive contains).

inventoryIds

[ID!]

Filter by inventories (OR within field).

titleContains

String

Partial match on title (case-insensitive contains).

search

String

Free-text search for a device list search box: a device matches when its title or any of its identifier values contains the value (case-insensitive), or its activation SIM phone number contains it. The phone is stored as digits only, so spaces and the characters +, -, (, ) and . are dropped from the value before it is compared with the phone. So 866104 finds a device by IMEI or by phone, and +49 151 by phone. A value of only those characters still matches by title and identifier.


DeviceOrder

Ordering options for devices.

Field
Type
Description

field

The field to order by.

direction

The direction to order.


DeviceModelFilter

Filtering options for device models.

Field
Type
Description

vendorIds

[ID!]

Filter by vendors (OR within field).

titleContains

String

Partial match on title (case-insensitive contains).

code

Exact code match.

supported

Boolean

Filter to models the platform supports (DeviceModel.supported).


DeviceCreateInput

Input for creating a new device.

Field
Type
Description

typeId

ID!

The device type ID.

modelId

ID!

The device model ID.

title

String

The device display name. If omitted or blank, the server generates "<vendor.title> <model.title> <identifier.value>" where the identifier is chosen by type priority: IMEI > SERIAL_NUMBER > MAC_ADDRESS, with fallback to identifiers[0] when none of the priority types are present. With no identifiers at all the generated title is "<vendor.title> <model.title>".

identifiers

The hardware identifiers. Optional: a device may be registered before its hardware is known. Identifiers can be added later with deviceIdentifierAdd.

inventoryId

ID

Optionally assign the new device to an existing inventory. When provided, the inventory must belong to the same workspace; the assignment is atomic with device creation (the device is not created if the assignment fails).


DeviceUpdateInput

Input for updating an existing device.

Field
Type
Description

id

ID!

The device ID to update.

version

Int

The current version for optimistic locking. If omitted, auto-increments without conflict check.

modelId

ID

The new device model.

title

String

The new display name.


DeviceDeleteInput

Input for deleting a device.

Field
Type
Description

id

ID!

The device ID to delete.

version

Int

The current version for optimistic locking. If omitted, auto-increments without conflict check.


DeviceIdentifierInput

Input for a device identifier.

Field
Type
Description

type

The type of identifier.

value

String!

The identifier value. 1 to 64 Unicode code points, measured after @trim has removed leading and trailing whitespace. An astral character such as an emoji counts as one, though a UTF-16 length reports it as two. The limit is not expressible in the schema and is enforced by the server: a longer value is rejected with VALIDATION_ERROR.

namespace

The namespace for uniqueness scope. Null means globally unique.


DeviceIdentifierAddInput

Input for adding an identifier to a device.

Field
Type
Description

deviceId

ID!

The device ID.

identifier

The identifier details.


DeviceIdentifierRemoveInput

Input for removing an identifier from a device.

Field
Type
Description

identifierId

ID!

The identifier ID to remove.


ApnSettingsInput

APN settings for deviceActivate.

Field
Type
Description

name

String!

The APN name: 1-40 characters of letters, digits, ., _ or -.

user

String

The APN username, if the carrier requires one: at most 40 characters of letters, digits, ., _, - or @.

password

String

The APN password, if the carrier requires one: at most 40 characters of letters, digits, ., _, - or @. Not saved in the device activation: it goes only into the activation SMS text, which the command queue keeps with the queued command. Ignored for MANUAL setup.


DeviceActivateInput

Input for activating a device: creates it with the given identifier, records SIM/APN data, sets it awaiting_connection, and for AUTOMATIC setup queues the SMS that pushes APN and server settings to it.

Field
Type
Description

setup

How the device receives its server settings.

modelId

ID!

The device model. Must be supported.

title

String

The device display name. For a new device, <model title> <identifier> when omitted or blank. For an existing device this activation attaches to, replaces its title when given and keeps it when omitted or blank.

identifier

String!

The identifier the model's protocol names a device by: the IMEI (15 digits) for most models, the serial number (6 to 10 digits, not all zeros, leading zeros kept) for Suntech models. Becomes the device's IMEI or SERIAL_NUMBER identifier, the serial number in the namespace of its protocol (suntech). Checked against the model: VALIDATION_ERROR on identifier otherwise.

phone

String

The SIM phone number the activation SMS is sent to: 5 to 20 digits, globally unique across the installation. Required for AUTOMATIC setup, optional for MANUAL.

apn

The APN settings pushed to the device. Required for AUTOMATIC setup, optional for MANUAL.


DeviceRelationCreateInput

Input for creating a relationship between devices.

Field
Type
Description

firstId

ID!

The first device ID.

secondId

ID!

The second device ID.

typeId

ID!

The relationship type ID.


DeviceRelationRemoveInput

Input for removing a device relationship.

Field
Type
Description

id

ID!

The relationship ID to remove.


DeviceTypeCreateInput

Input for creating a device type.

Field
Type
Description

code

The machine-readable code. Auto-generated from title if omitted.

title

String!

The display name.

order

Int

The display order. Auto-calculated as last position if omitted.

meta

The display properties.


DeviceTypeUpdateInput

Input for updating a device type.

Field
Type
Description

id

ID!

The item ID to update.

version

Int

The current version for optimistic locking. If omitted, auto-increments without conflict check.

title

String

The new display name.

order

Int

The new display order.

meta

The display properties.


DeviceStatusCreateInput

Input for creating a device status.

Field
Type
Description

code

The machine-readable code. Auto-generated from title if omitted.

title

String!

The display name.

order

Int

The display order. Auto-calculated as last position if omitted.

meta

The display properties.


DeviceStatusUpdateInput

Input for updating a device status.

Field
Type
Description

id

ID!

The item ID to update.

version

Int

The current version for optimistic locking. If omitted, auto-increments without conflict check.

title

String

The new display name.

order

Int

The new display order.

meta

The display properties.


Enums

DeviceIdType

The type of hardware identifier used to identify a device.

Value
Description

GUID

A GUID/UUID identifier.

IMEI

International Mobile Equipment Identity. A 15-digit number.

MEID_HEX

Mobile Equipment Identifier in hexadecimal format.

MEID_DEC

Mobile Equipment Identifier in decimal format.

MAC_ADDRESS

Media Access Control address of a network interface.

SERIAL_NUMBER

Manufacturer-assigned serial number.

CUSTOM

A custom identifier type defined by the workspace.


DeviceSetup

How a device activated by deviceActivate receives its server settings.

Value
Description

AUTOMATIC

The platform queues an SMS that pushes the APN and server settings to the device. Needs phone and apn.

MANUAL

The user enters the server settings on the device by hand, from DeviceActivation.server. No SMS is sent.


ActivationSmsOutcome

Whether deviceActivate with AUTOMATIC setup queued the SMS with the APN and server settings; some models take them in several SMS. Whether a queued SMS is sent and delivered later is not part of it. With SERVICE_UNAVAILABLE and MODEL_NOT_SUPPORTED no SMS is queued. With QUEUE_REFUSED the SMS queued before the refused one stay queued, but they do not carry all the settings. With any value but QUEUED the user enters the server settings on the device by hand, from DeviceActivation.server when it is set.

Value
Description

QUEUED

Every SMS is queued for sending.

SERVICE_UNAVAILABLE

The installation cannot send activation SMS.

MODEL_NOT_SUPPORTED

The platform cannot build the SMS for this device: its model or protocol has no such command, the installation publishes no server address, or the device lacks the identifier its protocol needs.

QUEUE_REFUSED

The command queue refused an SMS, for example because the queue is full. The SMS queued before it stay queued.


DeviceOrderField

Fields available for ordering devices.

Value
Description

TITLE

Order by title.


Pagination types

DeviceConnection

A paginated list of Device items.

Implements: Connection

Field
Type
Description

edges

A list of edges.

nodes

[Device!]!

A list of nodes in the connection (without edge metadata).

pageInfo

Information about the current page.

total

The total count of items matching the filter.


DeviceEdge

An edge in the Device connection.

Implements: Edge

Field
Type
Description

cursor

String!

An opaque cursor for this edge.

node

The device at the end of the edge.


DeviceTypeConnection

A paginated list of DeviceType items.

Implements: Connection

Field
Type
Description

edges

A list of edges.

nodes

A list of nodes in the connection (without edge metadata).

pageInfo

Information about the current page.

total

The total count of items matching the filter.


DeviceTypeEdge

An edge in the DeviceType connection.

Implements: Edge

Field
Type
Description

cursor

String!

An opaque cursor for this edge.

node

The device type at the end of the edge.


DeviceStatusConnection

A paginated list of DeviceStatus items.

Implements: Connection

Field
Type
Description

edges

A list of edges.

nodes

A list of nodes in the connection (without edge metadata).

pageInfo

Information about the current page.

total

The total count of items matching the filter.


DeviceStatusEdge

An edge in the DeviceStatus connection.

Implements: Edge

Field
Type
Description

cursor

String!

An opaque cursor for this edge.

node

The device status at the end of the edge.


DeviceModelConnection

A paginated list of DeviceModel items.

Implements: Connection

Field
Type
Description

edges

A list of edges.

nodes

A list of nodes in the connection (without edge metadata).

pageInfo

Information about the current page.

total

The total count of items matching the filter.


DeviceModelEdge

An edge in the DeviceModel connection.

Implements: Edge

Field
Type
Description

cursor

String!

An opaque cursor for this edge.

node

The device model at the end of the edge.


DeviceVendorConnection

A paginated list of DeviceVendor items.

Implements: Connection

Field
Type
Description

edges

A list of edges.

nodes

A list of nodes in the connection (without edge metadata).

pageInfo

Information about the current page.

total

The total count of items matching the filter.


DeviceVendorEdge

An edge in the DeviceVendor connection.

Implements: Edge

Field
Type
Description

cursor

String!

An opaque cursor for this edge.

node

The device vendor at the end of the edge.


DeviceRelationTypeConnection

A paginated list of DeviceRelationType items.

Implements: Connection

Field
Type
Description

edges

A list of edges.

nodes

A list of nodes in the connection (without edge metadata).

pageInfo

Information about the current page.

total

The total count of items matching the filter.


DeviceRelationTypeEdge

An edge in the DeviceRelationType connection.

Implements: Edge

Field
Type
Description

cursor

String!

An opaque cursor for this edge.

node

The device relation type at the end of the edge.


See also

Last updated

Was this helpful?