GraphQL reference: command-delivery

Generated from the schema this service serves, so it cannot fall behind it. The same schema is published as a file for tools and agents.

Endpoint	https://<your-host>/api/command-delivery/graphql
Auth plane	tenant — The ordinary application plane. Obtain a tenant access token by calling login then selectTenant on user-management, and authorize each call with the capability it names (for example device:write).
Authorize with	tenant access token
Schema file	/schema/command-delivery.graphql
Described	146 of 146 elements

Queries

commandBatches · commandBatchesById · commandBatchesByToken · commands · commandsById · commandsByToken · drainableCommands

commandBatches

Searches the tenant's command batches, newest first, one page at a time. Requires command:read. Reading a batch that targeted a group additionally requires device:read.

Returns CommandBatchSearchResults!

Argument	Type	Description
criteria	CommandBatchSearchCriteria!	Filters and page to return.

commandBatchesById

Returns the command batches with the given ids, in no particular order. Ids that match nothing are omitted; a non-numeric id is an error. Requires command:read. Reading a batch that targeted a group additionally requires device:read.

Returns [CommandBatch!]!

Argument	Type	Description
ids	[String!]!	Numeric ids of the batches, as strings. More than 1000 is refused with LIMIT_EXCEEDED.

commandBatchesByToken

Returns the command batches with the given tokens, in no particular order. Tokens that match nothing are omitted. Requires command:read. Reading a batch that targeted a group additionally requires device:read.

Returns [CommandBatch!]!

Argument	Type	Description
tokens	[String!]!	Tokens of the batches. More than 1000 is refused with LIMIT_EXCEEDED.

commands

Searches the tenant's commands, newest first, one page at a time. Requires command:read.

Returns CommandSearchResults!

Argument	Type	Description
criteria	CommandSearchCriteria!	Filters and page to return.

commandsById

Returns the commands with the given ids, in no particular order. Ids that match nothing are omitted; a non-numeric id is an error. Requires command:read.

Returns [Command!]!

Argument	Type	Description
ids	[String!]!	Numeric ids of the commands, as strings. More than 1000 is refused with LIMIT_EXCEEDED.

commandsByToken

Returns the commands with the given tokens, in no particular order. Tokens that match nothing are omitted. Requires command:read.

Returns [Command!]!

Argument	Type	Description
tokens	[String!]!	Tokens of the commands. More than 1000 is refused with LIMIT_EXCEEDED.

drainableCommands

Returns a device's still-waiting commands (HELD and PARKED) that have not expired, oldest first, for a transport delivering the backlog when the device comes back. Dispatch the list in the order given. Empty when nothing is waiting. Requires command:claim, a system-tier authority: tenant user tokens cannot call it.

Returns [Command!]!

Argument	Type	Description
deviceToken	String!	Token of the device whose backlog to read.
limit	Int	Maximum commands to return. Absent, null or 0 or less means 32; values above 1000 are capped at 1000. A device with more waiting returns the rest on a later call.

Mutations

cancelCommand · cancelCommandBatch · confirmCommandDispatch · createCommand · createCommandBatch · markCommandSent · parkCommand · releaseHeldCommands

cancelCommand

Cancels a command the platform still holds (QUEUED, HELD or PARKED) and returns it. A command in any other state is returned unchanged, so check the status you get back: a SENT command is already at the device and cannot be recalled. An unknown token is an error. Requires command:write.

Returns Command!

Argument	Type	Description
token	String!	Token of the command to cancel.

cancelCommandBatch

Calls off a fleet write: stops every command of the batch the platform still holds (QUEUED, HELD or PARKED) and reports what it did. Commands already sent cannot be recalled. An unknown batch token is an error. Requires command:write, and also device:read when the batch targeted a group.

Returns CancelCommandBatchResult!

Argument	Type	Description
token	String!	Token of the batch to cancel.

confirmCommandDispatch

For a transport that received a command on the live delivery stream: confirms, just before actuating, that the delivery is still the dispatch the platform holds. Returns a new dispatch nonce to quote when reporting the outcome, or null when the delivery is stale (re-armed, re-sent, answered, cancelled or its batch cancelled), in which case discard it without actuating. Requires command:claim, a system-tier authority.

Returns String

Argument	Type	Description
dispatchNonce	String!	The dispatch nonce carried in the delivery.
token	String!	Token of the command.

createCommand

Issues a command to one device. Returns the created command, or a typed rejection when the request is refused; a GraphQL error means the enqueue could not be decided at all. Re-sending a token you already used returns the original command. Requires command:write.

Returns CreateCommandResult!

Argument	Type	Description
request	CommandCreateRequest!	The command to issue.

createCommandBatch

Issues one command to many devices, named explicitly or resolved from an entity group, as a single recorded and cancellable operation. Returns the batch or a typed rejection; a GraphQL error means the batch could not be decided and nothing was created, so the token is unspent and the request can be retried. Requires command:write, and also device:read when targeting a group.

Returns CreateCommandBatchResult!

Argument	Type	Description
request	CommandBatchCreateRequest!	The batch to issue.

markCommandSent

For a transport that dispatches a backlog itself: claims a QUEUED, HELD or PARKED command for immediate delivery and moves it to SENT. Claim before dispatching. Returns the dispatch nonce, which must be quoted back when reporting the outcome; returns null if the command could not be claimed (already sent, answered or cancelled). Requires command:claim, a system-tier authority.

Returns String

Argument	Type	Description
token	String!	Token of the command to claim.

parkCommand

For a transport that found the device unreachable: hands a SENT command back, moving it to PARKED to be delivered on the device's next wake. Returns false, a settled outcome that must not be retried, when the command moved on (answered, cancelled, expired or re-claimed) or the nonce names a superseded dispatch. Requires command:park, a system-tier authority.

Returns Boolean!

Argument	Type	Description
dispatchNonce	String!	The dispatch nonce carried in the delivery this command arrived in.
token	String!	Token of the command.

releaseHeldCommands

Returns a device's HELD commands to the delivery queue (QUEUED) because the device has come back, and returns how many were released; zero when nothing was waiting. It queues rather than delivers: the delivery sweep still decides whether each command goes out. Requires command:wake, a system-tier authority.

Returns Int!

Argument	Type	Description
deviceToken	String!	Token of the device that came back.

Objects

CancelCommandBatchResult · Command · CommandBatch · CommandBatchDeviceRefusal · CommandBatchRefusalCount · CommandBatchRejection · CommandBatchSearchResults · CommandEnqueueRejection · CommandSearchResults · CreateCommandBatchResult · CreateCommandResult · SearchResultsPagination

CancelCommandBatchResult

object

What cancelling a batch was able to do. The four counts are not guaranteed to sum to matched; if matched exceeds their sum, some commands returned to the delivery queue after the cancel, and calling cancelCommandBatch again stops them.

Field	Type	Description
alreadyFinished	Int!	Commands that had already succeeded, failed, timed out, expired or been cancelled before this call. Nothing to do.
alreadySent	Int!	Commands already handed to their devices. They cannot be recalled and the devices will still act on them.
cancelled	Int!	Commands the platform still held and has now stopped. They will not be delivered.
matched	Int!	How many of the batch's commands exist right now. May be lower than the batch's accepted count, because commands can be deleted.

Command

object

A persisted command to one device. It is stored when accepted and moves through the lifecycle states in status until it settles; it is never fire-and-forget.

Implements Model, TokenReference, MetadataEntity

Field	Type	Description
batchToken	String	Token of the batch that created this command; null for a command issued one at a time.
createdAt	String	When the record was created, as an RFC 3339 timestamp.
deletedAt	String	When the record was deleted, as an RFC 3339 timestamp. Deleted records are not returned by this API, so this is null in practice.
deviceToken	String!	Token of the device the command is addressed to.
error	String	Why the command failed. Set when status is FAILED and a reason exists: the message the device reported, or the platform's own explanation when it gave up publishing or lost the answer. Null otherwise.
expiresAt	String	Instant after which an undelivered command expires, as an RFC 3339 timestamp. When none was given at creation the platform stamps its default time-to-live (7 days unless the deployment configures another). Null means the command does not expire.
id	ID!	Server-assigned numeric identifier, serialized as a string. Look entities up by token where one exists.
metadata	String	Free-form metadata supplied when the command was created, as a JSON document serialized to a string; null when none was supplied.
name	String!	The command's name, as defined in the command vocabulary of the device's profile.
payload	String	The command's arguments, as a JSON document serialized to a string; null when none was supplied.
queuedTime	String	When the command was accepted, as an RFC 3339 timestamp.
respondedTime	String	When the device's answer was recorded, as an RFC 3339 timestamp; null until a device answers.
responsePayload	String	The payload the device returned with its answer, as a JSON document serialized to a string; null until the device answers or when it returned none.
sentTime	String	When the command was last dispatched toward the device, as an RFC 3339 timestamp. Null if it has not been dispatched, or if the dispatch was handed back (the command returned to QUEUED or PARKED).
status	String!	Lifecycle state: one of QUEUED, HELD, SENT, PARKED, SUCCESSFUL, FAILED, TIMEOUT, EXPIRED or CANCELLED. QUEUED: accepted and awaiting its first dispatch decision. HELD: withheld because the device is known to be absent; it returns to QUEUED when the device comes back. SENT: dispatched toward the device and awaiting its response. PARKED: dispatched, but the transport found the device unreachable so nothing reached it; it is delivered on the device's next wake. SUCCESSFUL and FAILED: the device answered, reporting success or failure (FAILED is also set when the platform gives up publishing the command, or loses the device's answer; see error). TIMEOUT: the command expired while SENT without an answer. EXPIRED: the command expired while QUEUED, HELD or PARKED, so it never reached the device. CANCELLED: called off by a caller or by cancelling its batch. SUCCESSFUL, FAILED, TIMEOUT, EXPIRED and CANCELLED are terminal: no further transition occurs.
token	String!	Tenant-unique token. For a command created with createCommand it is the idempotency key the caller chose; for a command created by a batch it is chosen by the platform.
updatedAt	String	When the record was last modified, as an RFC 3339 timestamp.

CommandBatch

object

One command fanned out to many devices, kept as a record. A device the batch refused gets no command row, so this record is the only trace of what was attempted and what was refused.

Implements Model, TokenReference, MetadataEntity

Field	Type	Description
accepted	Int!	How many devices a command was enqueued for when the batch fired. A stored fact about that moment, not a live count; to see what those commands are doing now, search commands by batchToken. resolved equals accepted plus the sum of refusalCounts.
allowPartial	Boolean!	Whether the caller accepted a partial fan-out, in which devices that could not be enqueued were skipped rather than failing the whole batch.
cancelledAt	String	When the batch was first cancelled, as an RFC 3339 timestamp; null until it is cancelled. Cancelling again does not change it.
cancelledCount	Int	How many commands the first cancel call stopped; null until the batch is cancelled. A snapshot from that call, not a live count of CANCELLED commands.
createdAt	String	When the record was created, as an RFC 3339 timestamp.
deletedAt	String	When the record was deleted, as an RFC 3339 timestamp. Deleted records are not returned by this API, so this is null in practice.
groupToken	String	Token of the entity group the batch was fired at; null for a device-list batch.
groupVersion	Int	The frozen version of the group that the target set was resolved against. Null for a device-list batch and for a static group, which is not versioned.
id	ID!	Server-assigned numeric identifier, serialized as a string. Look entities up by token where one exists.
metadata	String	Free-form metadata supplied when the batch was created, as a JSON document serialized to a string; null when none was supplied.
name	String!	The command name every device in the batch received.
payload	String	The payload every device in the batch received, as a JSON document serialized to a string; null when none was supplied.
refusalCounts	[CommandBatchRefusalCount!]!	The exact number of refused devices per refusal code.
refusals	[CommandBatchDeviceRefusal!]!	A bounded sample of the devices that were refused (at most 100 per refusal code). Use refusalCounts for exact totals.
resolved	Int!	How many devices the target resolved to when the batch fired. A stored fact about that moment, not a live count.
targetKind	String!	How the target was specified: DEVICE_LIST (devices named explicitly) or GROUP (an entity group resolved when the batch fired).
token	String!	Tenant-unique token; the idempotency key supplied when the batch was created.
updatedAt	String	When the record was last modified, as an RFC 3339 timestamp.

CommandBatchDeviceRefusal

object

One device a batch did not enqueue to, and why.

Field	Type	Description
code	String!	Machine-readable classification, from the same open vocabulary as CommandEnqueueRejection.code (for example DEVICE_NOT_FOUND, COMMAND_NOT_IN_VOCABULARY, PAYLOAD_SCHEMA_VIOLATION or HELD_CEILING_EXCEEDED). Branch on this, not on reason.
deviceToken	String!	Token of the refused device, as it was named or resolved.
reason	String!	Human-readable explanation, safe to show to a user. Do not parse it.

CommandBatchRefusalCount

object

The exact number of devices refused for one code. Unlike the refusals sample, a count is never truncated.

Field	Type	Description
code	String!	The refusal code being counted.
count	Int!	How many devices were refused with that code.

CommandBatchRejection

object

Why a batch was refused. A refusal is a decided answer about the request, not a failure of the platform.

Field	Type	Description
code	String!	Stable, machine-readable classification: BATCH_TARGET_AMBIGUOUS, BATCH_TOO_LARGE, BATCH_GROUP_UNUSABLE (the group does not exist, collects something other than devices, was never published, or the named version does not exist or was named for a static group), PAYLOAD_NOT_JSON, METADATA_NOT_JSON, COMMAND_NAME_TOO_LONG, PAYLOAD_TOO_LARGE, METADATA_TOO_LARGE, EXPIRES_AT_INVALID, BATCH_PARTIAL_REFUSED or HELD_CEILING_EXCEEDED. Branch on this, never on reason. The list is open: treat an unrecognized code as a refusal you cannot classify. HELD_CEILING_EXCEEDED is temporary; the others will be refused again if re-sent unchanged. There is no TOKEN_IN_USE here: re-sending a batch token returns the original batch.
reason	String!	Human-readable explanation, safe to show to a user. Do not parse it.
refusalCounts	[CommandBatchRefusalCount!]!	The exact per-code totals behind the refusals sample.
refusals	[CommandBatchDeviceRefusal!]!	A bounded sample (at most 100) of the devices responsible. Populated only for BATCH_PARTIAL_REFUSED and empty for every other code.
resolved	Int	How many devices the target resolved to before the refusal. Null means no target set was established (the refusal came first); zero means the target genuinely resolved to no devices.

CommandBatchSearchResults

object

One page of command batches.

Field	Type	Description
pagination	SearchResultsPagination!	Where this page sits within all matching batches.
results	[CommandBatch!]!	The batches on this page, newest first.

CommandEnqueueRejection

object

Why an enqueue was refused. A refusal is a decided answer about the request, not a failure of the platform.

Field	Type	Description
code	String!	Stable, machine-readable classification: PAYLOAD_NOT_JSON, METADATA_NOT_JSON, COMMAND_NAME_TOO_LONG, PAYLOAD_TOO_LARGE, METADATA_TOO_LARGE, EXPIRES_AT_INVALID, HELD_CEILING_EXCEEDED, TOKEN_IN_USE, DEVICE_NOT_FOUND, COMMAND_NOT_IN_VOCABULARY, PAYLOAD_SCHEMA_VIOLATION, or COMMAND_REJECTED when a refusal arrived without a classification. Branch on this, never on reason. The list is open: treat an unrecognized code as a refusal you cannot classify, never as success. HELD_CEILING_EXCEEDED is the only temporary one (the tenant is holding its limit of commands for absent devices and the limit frees as they return); the rest will be refused again if re-sent unchanged. TOKEN_IN_USE means the token belongs to a command you do not own, which in practice is one the platform created for a batch; choose another token.
reason	String!	Human-readable explanation, safe to show to a user. Its wording may change; do not parse it.

CommandSearchResults

object

One page of commands.

Field	Type	Description
pagination	SearchResultsPagination!	Where this page sits within all matching commands.
results	[Command!]!	The commands on this page, newest first.

CreateCommandBatchResult

object

The outcome of createCommandBatch. Exactly one of batch and rejection is non-null.

Field	Type	Description
batch	CommandBatch	The batch that was created, or the original batch when the token was already in use. Null when the request was refused.
rejection	CommandBatchRejection	Why the batch was refused. Null when a batch was created.

CreateCommandResult

object

The outcome of createCommand. Exactly one of command and rejection is non-null.

Field	Type	Description
command	Command	The command that was created, or the original command when the token was already in use by one of your own commands. Null when the request was refused.
rejection	CommandEnqueueRejection	Why the request was refused. Null when a command was created.

SearchResultsPagination

object

Where one page of search results sits within the full result set. Positions are 1-based and inclusive.

Field	Type	Description
pageEnd	Int	Position of the last result of this page within the full result set (1-based, inclusive). Capped at totalRecords.
pageStart	Int	Position of the first result of this page within the full result set (1-based).
totalRecords	Int	Number of records matching the criteria across all pages.

Interfaces

MetadataEntity · Model · TokenReference

MetadataEntity

interface

An entity that carries free-form metadata.

Field	Type	Description
metadata	String	Free-form metadata as a JSON document serialized to a string; null when none was supplied.

Model

interface

Fields common to every stored record.

Field	Type	Description
createdAt	String	When the record was created, as an RFC 3339 timestamp.
deletedAt	String	When the record was deleted, as an RFC 3339 timestamp. Deleted records are not returned by this API, so this is null in practice.
id	ID!	Server-assigned numeric identifier, serialized as a string. Look entities up by token where one exists.
updatedAt	String	When the record was last modified, as an RFC 3339 timestamp.

TokenReference

interface

An entity addressed by a tenant-unique token.

Field	Type	Description
token	String!	Tenant-unique token that identifies the entity.

Input types

CommandBatchCreateRequest · CommandBatchSearchCriteria · CommandCreateRequest · CommandSearchCriteria

CommandBatchCreateRequest

input

Fields for issuing one command to many devices. Supply exactly one of deviceTokens and groupToken; both or neither is refused with BATCH_TARGET_AMBIGUOUS.

Input field	Type	Description
allowPartial	Boolean!	Required. When true, devices that cannot receive the command are skipped and recorded as refusals. When false, a batch in which any device cannot receive the command is refused whole (BATCH_PARTIAL_REFUSED) and nothing is created.
deviceTokens	[String!]	Tokens of the devices to command, at most 10000. The order is the order devices are admitted in when the batch is partially admitted. An empty list counts as not supplied.
expiresAt	String	RFC 3339 timestamp after which the batch's undelivered commands expire. Optional; when omitted the platform's default time-to-live applies.
groupToken	String	Token of an entity group of devices, resolved to its members when the batch fires. A dynamic group must have been published. A group that resolves to more than 10000 devices is refused with BATCH_TOO_LARGE. Requires device:read in addition to command:write.
groupVersion	Int	A specific frozen version of a dynamic group to resolve against. Omit for the group's active published version. Naming a version without a group, or for a static group, is refused.
metadata	String	Free-form metadata as a JSON document serialized to a string. Must be valid JSON. At most 65536 bytes (METADATA_TOO_LARGE). Optional.
name	String!	Name of the command every targeted device receives, as defined in each device's command vocabulary. At most 128 bytes, or the request is refused with COMMAND_NAME_TOO_LONG.
payload	String	The payload every device receives, as a JSON document serialized to a string. Must be valid JSON. At most 65536 bytes (PAYLOAD_TOO_LARGE). Optional.
token	String!	Idempotency key for the whole batch, unique within the tenant. Re-sending a token that already names a batch returns that batch unchanged and admits no further devices.

CommandBatchSearchCriteria

input

Filters and paging for searching command batches. All supplied filters must match. Results are newest first.

Input field	Type	Description
groupToken	String	Only batches fired at this entity group. Device-list batches never match.
name	String	Only batches that fanned out this command name.
pageNumber	Int!	Page to return, starting at 1; values below 1 are treated as 1.
pageSize	Int!	Results per page. Values below 1 become 100; values above 1000 are capped at 1000.
targetKind	String	Only batches of this kind: DEVICE_LIST or GROUP. An unrecognized value matches nothing rather than raising an error.

CommandCreateRequest

input

Fields for issuing a command to one device.

Input field	Type	Description
deviceToken	String!	Token of the device to command.
expiresAt	String	RFC 3339 timestamp after which the command expires if undelivered. Optional; when omitted the platform's default time-to-live applies.
metadata	String	Free-form metadata as a JSON document serialized to a string. Must be valid JSON. At most 65536 bytes (METADATA_TOO_LARGE). Optional.
name	String!	Name of the command, which must exist in the command vocabulary of the device's profile; otherwise the request is refused with COMMAND_NOT_IN_VOCABULARY. At most 128 bytes, or the request is refused with COMMAND_NAME_TOO_LONG.
payload	String	The command's arguments as a JSON document serialized to a string. Must be valid JSON and, when the command definition declares a schema, conform to it. At most 65536 bytes (PAYLOAD_TOO_LARGE). Optional.
token	String!	Idempotency key for the command, unique within the tenant. Re-sending a token you already used returns the original command instead of creating a second one.

CommandSearchCriteria

input

Filters and paging for searching commands. All supplied filters must match. Results are newest first.

Input field	Type	Description
batchToken	String	Only commands created by this batch. This is how to ask what a fleet write is doing now, since the batch record keeps only counts from the moment it fired. Combine with status or statuses. Rows come back in the order the batch admitted its devices.
deviceToken	String	Only commands addressed to this device.
pageNumber	Int!	Page to return, starting at 1; values below 1 are treated as 1.
pageSize	Int!	Results per page. Values below 1 become 100; values above 1000 are capped at 1000.
status	String	Only commands in exactly this lifecycle state (for example HELD).
statuses	[String!]	Only commands in any of these lifecycle states. Combined with status, a command must satisfy both. An empty list is ignored rather than matching nothing.