Devices
Actions in the devices namespace of the Nexigon Hub API.
Badges mark actions of the Device API and the Admin API, whose compatibility differs from other actions.
devices_Query
POST/api/v1/actions/invoke/devices_QueryAdmin API
Query the devices of the instance.
Request QueryDevicesAction
No fields. Send an empty JSON object.
Response QueryDevicesOutput
devicesarray<object>QueryDevicesItemList of devices.
5 fields
deviceIdstringDeviceIdID of the device.
projectIdstringProjectIdProject ID of the device.
isConnectedbooleanIndicates whether the device is currently connected.
lastConnectedAtstring (date-time)TimestampoptionalTimestamp when the device was last connected (current or most recent connection).
currentConnectionDurationSecsintegeroptionalDuration of the current connection in seconds (null if not connected).
Example
curl --fail-with-body \
-H "Authorization: Bearer $NEXIGON_TOKEN" \
-H "Content-Type: application/json" \
-d '{}' \
$NEXIGON_HUB_URL/api/v1/actions/invoke/devices_Query{
"devices": [
{
"deviceId": "<device-id>",
"projectId": "<project-id>",
"isConnected": true
}
]
}devices_GetDetails
POST/api/v1/actions/invoke/devices_GetDetails
Get information about a device.
Request GetDeviceDetailsAction
deviceIdstringDeviceIdID of the device.
Response GetDeviceDetailsOutput
groupsarray<object>DeviceGroupGroups currently assigned to this device.
5 fields
groupIdstringDeviceGroupIdprojectIdstringProjectIdnamestringUnique within the project, ignoring case and surrounding whitespace.
colorstringDeviceGroupColoroptional- Group color must be a six-digit hexadecimal color, such as #3b82f6.
descriptionstringoptional
profilesarray<object>AssignedDeviceProfileProfiles assigned to this device, in the order they apply.
3 fields
profileobjectDeviceProfileSummary6 fields
profileIdstringDeviceProfileIdprojectIdstringProjectIddisplayNamestringDisplay name, which does not have to be unique.
descriptionstringoptionalrevisionintegerLatest revision. Devices always use the latest revision.
deviceCountintegerNumber of devices the profile is assigned to.
modeobjectDeviceProfileMode3 variants
One of the following, identified by
mode:mode: "Latest"Use every revision as soon as it is saved.
mode: "Pinned"Use one specific revision.
revisioninteger
mode: "Rollout"Use the revision of the profile's rollout once the rollout reaches the device. The device then applies the revision, even if it already uses it.
A device that switches to this mode keeps its current revision until then. A device that gets the profile in this mode has no revision until then, so that the profile sets no values on it.
revisionintegeroptionalRevision that the device uses. Absent if the profile is in rollout mode and its rollout has not reached the device.
deviceIdstringDeviceIdID of the device.
projectIdstringProjectIdProject ID of the device.
fingerprintIdstringDeviceFingerprintIdFingerprint ID the device.
namestringoptionalName of the device.
isConnectedbooleanIndicates whether the device is online.
lastSeenstring (date-time)TimestampoptionalTime when the device last disconnected, or when it was created if it never connected. Unlike the connection log, it survives log retention.
certificatesarray<object>DeviceCertificateCertificates of the device.
4 fields
certificateIdstringDeviceCertificateIdID of the certificate.
statusstringDeviceCertificateStatusStatus of the certificate.
"Pending"The certificate is pending.
"Active"The certificate is active.
"Rejected"The certificate has been rejected.
"Revoked"The certificate has been revoked.
"Conflict"The certificate fingerprint was seen on multiple devices.
fingerprintstringCertificateFingerprintFingerprint of the certificate.
firstSeenstring (date-time)TimestampTimestamp when the certificate was first seen.
connectionsarray<object>DeviceConnectionConnections of the device.
4 fields
connectionIdstringDeviceConnectionIdID of the connection.
nodeIdstringClusterNodeIdID of the cluster node.
connectedAtstring (date-time)TimestampTimestamp when the connection was established.
connectedForSecsintegerDuration of the connection in seconds.
Example
curl --fail-with-body \
-H "Authorization: Bearer $NEXIGON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"deviceId":"<device-id>"}' \
$NEXIGON_HUB_URL/api/v1/actions/invoke/devices_GetDetails{
"groups": [
{
"groupId": "<device-group-id>",
"projectId": "<project-id>",
"name": "<name>"
}
],
"profiles": [
{
"profile": {
"profileId": "<device-profile-id>",
"projectId": "<project-id>",
"displayName": "<display-name>",
"revision": 1,
"deviceCount": 1
},
"mode": {
"mode": "Pinned",
"revision": 1
}
}
],
"deviceId": "<device-id>",
"projectId": "<project-id>",
"fingerprintId": "<device-fingerprint-id>",
"isConnected": true,
"certificates": [
{
"certificateId": "<device-certificate-id>",
"status": "Pending",
"fingerprint": "<certificate-fingerprint>",
"firstSeen": "2026-01-01T12:00:00Z"
}
],
"connections": [
{
"connectionId": "<device-connection-id>",
"nodeId": "<cluster-node-id>",
"connectedAt": "2026-01-01T12:00:00Z",
"connectedForSecs": 1
}
]
}devices_Create
POST/api/v1/actions/invoke/devices_Create
Create a new device.
Request CreateDeviceAction
projectIdstringProjectIdID of the project.
fingerprintstringDeviceFingerprintFingerprint of the device.
Response CreateDeviceOutput
deviceIdstringDeviceIdID of the device.
Example
curl --fail-with-body \
-H "Authorization: Bearer $NEXIGON_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"projectId": "<project-id>",
"fingerprint": "<device-fingerprint>"
}' \
$NEXIGON_HUB_URL/api/v1/actions/invoke/devices_Create{
"deviceId": "<device-id>"
}devices_Delete
POST/api/v1/actions/invoke/devices_Delete
Delete a device.
Request DeleteDeviceAction
deviceIdstringDeviceIdID of the device.
Response Empty
No fields. The response is an empty JSON object.
Example
curl --fail-with-body \
-H "Authorization: Bearer $NEXIGON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"deviceId":"<device-id>"}' \
$NEXIGON_HUB_URL/api/v1/actions/invoke/devices_Delete{}devices_SetName
POST/api/v1/actions/invoke/devices_SetName
Set the name of a device.
Request SetDeviceNameAction
deviceIdstringDeviceIdID of the device.
namestringoptionalNew name of the device.
- Device name must be between 1 and 128 characters.
Response Empty
No fields. The response is an empty JSON object.
Example
curl --fail-with-body \
-H "Authorization: Bearer $NEXIGON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"deviceId":"<device-id>"}' \
$NEXIGON_HUB_URL/api/v1/actions/invoke/devices_SetName{}devices_IssueDeviceToken
POST/api/v1/actions/invoke/devices_IssueDeviceTokenDevice API
Issue a token that proves a device's identity to an external system.
The token is a JWT signed by Nexigon Hub that carries the device ID and the given
claims. An external backend validates it with devices_ValidateDeviceToken.
Note: Only use this action for integration with external systems. The token does not replace the credentials a device uses to connect to Nexigon Hub.
Request IssueDeviceTokenAction
deviceIdstringDeviceIdID of the device.
validForSecsintegeroptionalToken validity duration in seconds. Defaults to 600 seconds (10 minutes).
- Token validity must be between 1 second and 1 year.
claimsanyJsonValueoptionalAdditional user-defined claims.
Nexigon Hub rejects claims larger than the instance's limit, 4 KiB by default.
Response IssueDeviceTokenOutput
jwtstringJwtIssued JWT.
Example
curl --fail-with-body \
-H "Authorization: Bearer $NEXIGON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"deviceId":"<device-id>"}' \
$NEXIGON_HUB_URL/api/v1/actions/invoke/devices_IssueDeviceToken{
"jwt": "<jwt>"
}devices_ValidateDeviceToken
POST/api/v1/actions/invoke/devices_ValidateDeviceToken
Validate a token issued with devices_IssueDeviceToken.
Returns the device ID and claims of a valid token. Tokens of deleted devices, of devices in deleted projects, and of devices in deactivated organizations are invalid.
Note: Only use this action for integration with external systems.
Request ValidateDeviceTokenAction
jwtstringJwtJWT to validate.
Response ValidateDeviceTokenOutput
One of the following, identified by result:
result: "Invalid"The JWT is invalid.
result: "Valid"The JWT is valid.
deviceIdstringDeviceIdID of the device.
claimsanyJsonValueUser-defined claims.
Example
curl --fail-with-body \
-H "Authorization: Bearer $NEXIGON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"jwt":"<jwt>"}' \
$NEXIGON_HUB_URL/api/v1/actions/invoke/devices_ValidateDeviceToken{
"result": "Valid",
"deviceId": "<device-id>",
"claims": {}
}devices_AddCertificate
POST/api/v1/actions/invoke/devices_AddCertificate
Add a device certificate.
Request AddDeviceCertificateAction
deviceIdstringDeviceIdID of the device.
fingerprintstringCertificateFingerprintFingerprint of the certificate.
statusstringDeviceCertificateStatusoptionalInitial status of the certificate.
Defaults to
Pending."Pending"The certificate is pending.
"Active"The certificate is active.
"Rejected"The certificate has been rejected.
"Revoked"The certificate has been revoked.
"Conflict"The certificate fingerprint was seen on multiple devices.
Response AddDeviceCertificateOutput
certificateIdstringDeviceCertificateIdID of the certificate.
Example
curl --fail-with-body \
-H "Authorization: Bearer $NEXIGON_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"deviceId": "<device-id>",
"fingerprint": "<certificate-fingerprint>"
}' \
$NEXIGON_HUB_URL/api/v1/actions/invoke/devices_AddCertificate{
"certificateId": "<device-certificate-id>"
}devices_DeleteCertificate
POST/api/v1/actions/invoke/devices_DeleteCertificate
Delete a device certificate.
Request DeleteDeviceCertificateAction
certificateIdstringDeviceCertificateIdID of the certificate.
Response Empty
No fields. The response is an empty JSON object.
Example
curl --fail-with-body \
-H "Authorization: Bearer $NEXIGON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"certificateId":"<device-certificate-id>"}' \
$NEXIGON_HUB_URL/api/v1/actions/invoke/devices_DeleteCertificate{}devices_SetCertificateStatus
POST/api/v1/actions/invoke/devices_SetCertificateStatus
Set the status of a device certificate.
Request SetDeviceCertificateStatusAction
certificateIdstringDeviceCertificateIdID of the certificate.
statusstringDeviceCertificateStatusNew status of the certificate.
"Pending"The certificate is pending.
"Active"The certificate is active.
"Rejected"The certificate has been rejected.
"Revoked"The certificate has been revoked.
"Conflict"The certificate fingerprint was seen on multiple devices.
Response Empty
No fields. The response is an empty JSON object.
Example
curl --fail-with-body \
-H "Authorization: Bearer $NEXIGON_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"certificateId": "<device-certificate-id>",
"status": "Pending"
}' \
$NEXIGON_HUB_URL/api/v1/actions/invoke/devices_SetCertificateStatus{}devices_RegisterConnection
POST/api/v1/actions/invoke/devices_RegisterConnection
Register a connection of a device to a cluster node.
Nexigon Hub invokes this action internally. Clients do not need it.
Request RegisterDeviceConnectionAction
deviceIdstringDeviceIdID of the device.
nodeIdstringClusterNodeIdID of the cluster node.
connectionIdstringDeviceConnectionIdPre-generated ID of the connection.
Response RegisterDeviceConnectionOutput
connectionIdstringDeviceConnectionIdID of the connection.
Example
curl --fail-with-body \
-H "Authorization: Bearer $NEXIGON_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"deviceId": "<device-id>",
"nodeId": "<cluster-node-id>",
"connectionId": "<device-connection-id>"
}' \
$NEXIGON_HUB_URL/api/v1/actions/invoke/devices_RegisterConnection{
"connectionId": "<device-connection-id>"
}devices_UnregisterConnection
POST/api/v1/actions/invoke/devices_UnregisterConnection
Unregister a connection of a device to a cluster node.
Nexigon Hub invokes this action internally. Clients do not need it.
Request UnregisterDeviceConnectionAction
connectionIdstringDeviceConnectionIdID of the connection.
endReasonstringConnectionEndReasonReason for ending the connection.
"Unknown"Unknown reason (fallback).
"Disconnected"Device disconnected normally.
"NodeCrashed"Connection ended due to cluster node crash or heartbeat timeout.
"ServerShutdown"Connection ended due to graceful server shutdown.
Response Empty
No fields. The response is an empty JSON object.
Example
curl --fail-with-body \
-H "Authorization: Bearer $NEXIGON_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"connectionId": "<device-connection-id>",
"endReason": "Unknown"
}' \
$NEXIGON_HUB_URL/api/v1/actions/invoke/devices_UnregisterConnection{}devices_QueryConnections
POST/api/v1/actions/invoke/devices_QueryConnections
Query the connection history of a device.
Request QueryDeviceConnectionsAction
deviceIdstringDeviceIdID of the device.
limitintegeroptionalLimit results (default 100).
- Limit must be between 1 and 1000.
activeOnlybooleanoptionalInclude only active connections.
Response QueryDeviceConnectionsOutput
connectionsarray<object>DeviceConnectionLogList of connections.
6 fields
connectionIdstringDeviceConnectionIdID of the connection.
nodeIdstringClusterNodeIdID of the cluster node.
connectedAtstring (date-time)TimestampTimestamp when the connection was established.
endedAtstring (date-time)TimestampoptionalTimestamp when the connection ended (null if still connected).
endReasonstringConnectionEndReasonoptionalReason why the connection ended (null if still connected).
"Unknown"Unknown reason (fallback).
"Disconnected"Device disconnected normally.
"NodeCrashed"Connection ended due to cluster node crash or heartbeat timeout.
"ServerShutdown"Connection ended due to graceful server shutdown.
durationSecsintegerDuration of the connection in seconds.
Example
curl --fail-with-body \
-H "Authorization: Bearer $NEXIGON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"deviceId":"<device-id>"}' \
$NEXIGON_HUB_URL/api/v1/actions/invoke/devices_QueryConnections{
"connections": [
{
"connectionId": "<device-connection-id>",
"nodeId": "<cluster-node-id>",
"connectedAt": "2026-01-01T12:00:00Z",
"durationSecs": 1
}
]
}devices_IssueHttpProxyToken
POST/api/v1/actions/invoke/devices_IssueHttpProxyToken
Issue a HTTP proxy JWT.
Request IssueDeviceHttpProxyTokenAction
deviceIdstringDeviceIdID of the device.
validForSecsintegeroptionalToken validity duration in seconds.
- Token validity must be between 1 second and 1 year.
hostnamestringoptionalHostname to accept requests for.
Defaults to a device-specific pseudo-random subdomain of the instance domain. A custom hostname requires a configured instance URL or legacy domain setting and must differ from the Nexigon Hub hostname.
- Hostname must be between 1 and 253 characters.
- Hostname must be a valid DNS hostname.
portintegeroptionalDevice port to proxy to.
Defaults to
80.- Port must be between 1 and 65535.
redirectstringoptionalRedirect URL in case the token is expired or invalid.
- Redirect URL must be between 1 and 2048 characters.
Response IssueDeviceHttpProxyTokenOutput
jwtstringJwtJWT proxy token.
urlstringProxy URL.
Example
curl --fail-with-body \
-H "Authorization: Bearer $NEXIGON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"deviceId":"<device-id>"}' \
$NEXIGON_HUB_URL/api/v1/actions/invoke/devices_IssueHttpProxyToken{
"jwt": "<jwt>",
"url": "<url>"
}devices_ValidateHttpProxyToken
POST/api/v1/actions/invoke/devices_ValidateHttpProxyToken
Validate an HTTP proxy JWT.
Nexigon Hub invokes this action internally. Clients do not need it.
Request ValidateDeviceHttpProxyTokenAction
jwtstringJwtJWT to validate.
Response ValidateDeviceHttpProxyTokenOutput
One of the following, identified by result:
result: "Invalid"The JWT is invalid.
redirectstringoptionalURL to redirect to.
result: "Valid"The JWT is valid.
deviceIdstringDeviceIdID of the device.
issuerobjectActoroptionalActor that issued the token.
Missing on proxy tokens issued before issuer tracking was introduced.
7 variants
One of the following, identified by
actor:actor: "Anonymous"An anonymous, unauthenticated actor.
actor: "System"The system itself, typically used for internal actions.
actor: "Device"A device authenticated via a specific deployment token.
deviceIdstringDeviceIdID of the device.
tokenIdstringDeploymentTokenIdID of the deployment token used for authentication.
actor: "User"A user typically authenticated via a user session.
userIdstringUserIdID of the user.
actor: "UserToken"A user authenticated via a specific token.
userIdstringUserIdID of the user.
tokenIdstringUserTokenIdID of the user token used for authentication.
actor: "ClusterNode"A cluster node.
nodeIdstringClusterNodeIdID of the cluster node.
actor: "OrganizationApiToken"An organization API token.
organizationIdstringOrganizationIdID of the organization.
tokenIdstringOrganizationApiTokenIdID of the API token.
hostnamestringoptionalHostname to accept requests for.
portintegeroptionalDevice port to proxy to.
Example
curl --fail-with-body \
-H "Authorization: Bearer $NEXIGON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"jwt":"<jwt>"}' \
$NEXIGON_HUB_URL/api/v1/actions/invoke/devices_ValidateHttpProxyToken{
"result": "Invalid"
}devices_PublishEvents
POST/api/v1/actions/invoke/devices_PublishEventsDevice API
Publish events of a device.
Nexigon Hub stores events as a history of device behavior. Each event has an ID that is unique per device. An event published again with the same ID is not stored again, so publishing can safely be retried.
Nexigon Hub may limit the number of events that a device can store per day and
per billing period. If storing the new events of a batch would exceed a limit,
Nexigon Hub rejects the whole batch with a RateLimited error that states when
to retry. A batch with more new events than a limit allows fails with an
Invalid error. Events with an already stored ID do not count toward the limits.
Nexigon Hub also limits the size of each event, 4 KiB by default, and the number
of events in a batch, 1000 by default. A batch that exceeds either limit fails with
an Invalid error.
Request PublishDeviceEventsAction
deviceIdstringDeviceIdID of the device.
eventsarray<object>DeviceEventEvents to publish.
7 fields
eventIdstringDeviceEventIdID of the event.
categorystringoptionalCategory identifying the type of the event. Keep the set of categories small.
- Event category must be between 1 and 128 characters.
severitystringDeviceEventSeveritySeverity of the event.
"Trace"Tracing event.
"Debug"Debugging event.
"Info"Informational event.
"Warning"Warning event.
"Error"Error event.
"Critical"Critical event.
bodyanyJsonValueEvent body.
attributesmap<string, any>JsonValueEvent attributes.
emittedAtstring (date-time)TimestampTimestamp when the event was emitted.
receivedAtstring (date-time)TimestampoptionalTimestamp when Nexigon Hub received the event. Nexigon Hub sets it and ignores the value in published events.
Response Empty
No fields. The response is an empty JSON object.
Example
curl --fail-with-body \
-H "Authorization: Bearer $NEXIGON_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"deviceId": "<device-id>",
"events": [
{
"eventId": "<device-event-id>",
"severity": "Trace",
"body": {},
"attributes": {
"<key>": {}
},
"emittedAt": "2026-01-01T12:00:00Z"
}
]
}' \
$NEXIGON_HUB_URL/api/v1/actions/invoke/devices_PublishEvents{}devices_QueryEvents
POST/api/v1/actions/invoke/devices_QueryEvents
Query device events.
Request QueryDeviceEventsAction
pageobjectPageRequestoptionalOpt into cursor pagination. Without this field, the existing limit applies.
2 fields
limitintegeroptionalMaximum number of items. The default depends on the endpoint and the ceiling is configured by the Hub operator (1000 by default).
- Page limit must be positive.
cursorstringPageCursoroptionalContinue the same endpoint, scope, filters, and ordering.
deviceIdstringDeviceIdID of the device.
limitintegeroptionalLimit the number of events to return.
Default to
100.- Limit must be between 1 and 1000.
Response QueryDeviceEventsOutput
pageobjectPageInfooptionalPresent when cursor pagination was requested.
1 field
nextCursorstringPageCursoroptionalCursor for the next page; absent when no more matching rows were visible.
eventsarray<object>DeviceEventList of events.
7 fields
eventIdstringDeviceEventIdID of the event.
categorystringoptionalCategory identifying the type of the event. Keep the set of categories small.
- Event category must be between 1 and 128 characters.
severitystringDeviceEventSeveritySeverity of the event.
"Trace"Tracing event.
"Debug"Debugging event.
"Info"Informational event.
"Warning"Warning event.
"Error"Error event.
"Critical"Critical event.
bodyanyJsonValueEvent body.
attributesmap<string, any>JsonValueEvent attributes.
emittedAtstring (date-time)TimestampTimestamp when the event was emitted.
receivedAtstring (date-time)TimestampoptionalTimestamp when Nexigon Hub received the event. Nexigon Hub sets it and ignores the value in published events.
Example
curl --fail-with-body \
-H "Authorization: Bearer $NEXIGON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"deviceId":"<device-id>"}' \
$NEXIGON_HUB_URL/api/v1/actions/invoke/devices_QueryEvents{
"events": [
{
"eventId": "<device-event-id>",
"severity": "Trace",
"body": {},
"attributes": {
"<key>": {}
},
"emittedAt": "2026-01-01T12:00:00Z"
}
]
}devices_SetProperty
POST/api/v1/actions/invoke/devices_SetPropertyDevice API
Set a property of a device.
A property is a named JSON value of a device. Setting a property replaces the device's own value and increments the property's version. With an expected version, the property is only updated if its version still matches (compare-and-swap). Devices cannot change protected properties.
Request SetDevicePropertyAction
deviceIdstringDeviceIdID of the device.
namestringName of the property.
- Property name must be between 1 and 256 characters.
- Property name must start with a letter or digit and contain only letters, digits, dots, underscores, or hyphens.
valueanyJsonValueValue of the property.
Nexigon Hub rejects values larger than the instance's limit, 64 KiB by default.
protectedbooleanoptionalIndicates whether the property should be protected.
expectedVersioninteger (64-bit)optionalIf set, the property is only updated when its current version matches this value (compare-and-swap). Returns
VersionConflictwhen the version does not match, orDeletedwhen the property no longer exists.
Response SetDevicePropertyOutput
One of the following, identified by result:
result: "Set"The property was set successfully.
versioninteger (64-bit)optionalThe new version of the property.
Absent in responses of Nexigon Hub 2026.3 and earlier.
result: "VersionConflict"The property was not updated because its version did not match the expected version (compare-and-swap conflict).
currentVersioninteger (64-bit)The current version of the property.
result: "Deleted"The property was not updated because it has been deleted while an expected version was specified.
Example
curl --fail-with-body \
-H "Authorization: Bearer $NEXIGON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"deviceId":"<device-id>","name":"<name>","value":{}}' \
$NEXIGON_HUB_URL/api/v1/actions/invoke/devices_SetProperty{
"result": "Set"
}devices_GetProperty
POST/api/v1/actions/invoke/devices_GetPropertyDevice API
Get a property of a device.
The value combines the values of the device's profiles with the device's own value.
Request GetDevicePropertyAction
deviceIdstringDeviceIdID of the device.
namestringName of the property.
- Property name must be between 1 and 256 characters.
- Property name must start with a letter or digit and contain only letters, digits, dots, underscores, or hyphens.
Response GetDevicePropertyOutput
One of the following, identified by result:
result: "NotFound"The property was not found.
result: "Found"The property was found.
namestringName of the property.
valueanyJsonValueValue of the property.
protectedbooleanIndicates whether the property is protected.
versioninteger (64-bit)Version number.
Increases with every write to the device's own value, even with an unchanged value, and with every change of the device's profiles that affects the property.
lastUpdatedstring (date-time)TimestampLast time the property was updated.
Example
curl --fail-with-body \
-H "Authorization: Bearer $NEXIGON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"deviceId":"<device-id>","name":"<name>"}' \
$NEXIGON_HUB_URL/api/v1/actions/invoke/devices_GetProperty{
"result": "Found",
"name": "<name>",
"value": {},
"protected": true,
"version": 1,
"lastUpdated": "2026-01-01T12:00:00Z"
}devices_RemoveProperty
POST/api/v1/actions/invoke/devices_RemoveProperty
Remove a property value set on a device.
Values that the device's profiles set for the property remain.
Request RemoveDevicePropertyAction
deviceIdstringDeviceIdID of the device.
namestringName of the property.
- Property name must be between 1 and 256 characters.
- Property name must start with a letter or digit and contain only letters, digits, dots, underscores, or hyphens.
Response RemoveDevicePropertyOutput
One of the following, identified by result:
result: "NotFound"The device has no value of its own for the property.
result: "Removed"The property was removed.
Example
curl --fail-with-body \
-H "Authorization: Bearer $NEXIGON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"deviceId":"<device-id>","name":"<name>"}' \
$NEXIGON_HUB_URL/api/v1/actions/invoke/devices_RemoveProperty{
"result": "NotFound"
}devices_QueryProperties
POST/api/v1/actions/invoke/devices_QueryProperties
Query the properties of a device.
Request QueryDevicePropertiesAction
deviceIdstringDeviceIdID of the device.
Response QueryDevicePropertiesOutput
propertiesmap<string, object>DevicePropertyList of properties.
5 fields
namestringName of the property.
valueanyJsonValueValue of the property.
protectedbooleanIndicates whether the property is protected.
versioninteger (64-bit)Version number.
Increases with every write to the device's own value, even with an unchanged value, and with every change of the device's profiles that affects the property.
lastUpdatedstring (date-time)TimestampLast time the property was updated.
Example
curl --fail-with-body \
-H "Authorization: Bearer $NEXIGON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"deviceId":"<device-id>"}' \
$NEXIGON_HUB_URL/api/v1/actions/invoke/devices_QueryProperties{
"properties": {
"<key>": {
"name": "<name>",
"value": {},
"protected": true,
"version": 1,
"lastUpdated": "2026-01-01T12:00:00Z"
}
}
}devices_QueryPropertySources
POST/api/v1/actions/invoke/devices_QueryPropertySources
- Unstable (feature
device_profiles)
Query where the property values of a device come from.
Request QueryDevicePropertySourcesAction
deviceIdstringDeviceIdID of the device.
Response QueryDevicePropertySourcesOutput
propertiesmap<string, object>DevicePropertySourcesSources of every property that a profile or the device itself sets.
3 fields
versioninteger (64-bit)Version of the property, for compare-and-swap writes of the device value.
profilesarray<object>DevicePropertyProfileValueValues set by the device's profiles, in the order they apply.
4 fields
profileIdstringDeviceProfileIdrevisionintegerRevision of the profile that sets the value.
valueanyJsonValueprotectedboolean
deviceobjectDevicePropertyDeviceValueoptionalValue set on the device itself.
2 fields
valueanyJsonValueprotectedboolean
Example
curl --fail-with-body \
-H "Authorization: Bearer $NEXIGON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"deviceId":"<device-id>"}' \
$NEXIGON_HUB_URL/api/v1/actions/invoke/devices_QueryPropertySources{
"properties": {
"<key>": {
"version": 1,
"profiles": [
{
"profileId": "<device-profile-id>",
"revision": 1,
"value": {},
"protected": true
}
]
}
}
}devices_QueryAuditLog
POST/api/v1/actions/invoke/devices_QueryAuditLog
Query the audit log of a device.
Request QueryDeviceAuditLogAction
pageobjectPageRequestoptionalOpt into cursor pagination. Without this field, the existing limit applies.
2 fields
limitintegeroptionalMaximum number of items. The default depends on the endpoint and the ceiling is configured by the Hub operator (1000 by default).
- Page limit must be positive.
cursorstringPageCursoroptionalContinue the same endpoint, scope, filters, and ordering.
deviceIdstringDeviceIdID of the device.
Response QueryDeviceAuditLogOutput
pageobjectPageInfooptionalPresent when cursor pagination was requested.
1 field
nextCursorstringPageCursoroptionalCursor for the next page; absent when no more matching rows were visible.
eventsarray<object>AuditLogEventList of audit log events.
7 fields
eventIdstringAuditLogEventIdID of the audit log event.
actorobjectActorActor causing the event.
7 variants
One of the following, identified by
actor:actor: "Anonymous"An anonymous, unauthenticated actor.
actor: "System"The system itself, typically used for internal actions.
actor: "Device"A device authenticated via a specific deployment token.
deviceIdstringDeviceIdID of the device.
tokenIdstringDeploymentTokenIdID of the deployment token used for authentication.
actor: "User"A user typically authenticated via a user session.
userIdstringUserIdID of the user.
actor: "UserToken"A user authenticated via a specific token.
userIdstringUserIdID of the user.
tokenIdstringUserTokenIdID of the user token used for authentication.
actor: "ClusterNode"A cluster node.
nodeIdstringClusterNodeIdID of the cluster node.
actor: "OrganizationApiToken"An organization API token.
organizationIdstringOrganizationIdID of the organization.
tokenIdstringOrganizationApiTokenIdID of the API token.
eventstringType of the event that was recorded.
dataanyJsonValueAdditional audit data associated with the event.
createdAtstring (date-time)TimestampTimestamp indicating when the audit log event was recorded.
actionobjectAuditLogEventActionoptionalAction the event has been caused by (if any).
1 field
actionIdstringAuditLogActionIdID of the action.
jobobjectAuditLogEventJoboptionalJob the event has been caused by (if any).
1 field
jobIdstringJobIdID of the job.
referencesobjectAuditLogReferencesoptionalNames of the actors of the returned events.
Absent in responses of Nexigon Hub 2026.3 and earlier.
3 fields
usersarray<object>AuditLogUserReferenceUsers acting directly or through a user token.
3 fields
userIdstringUserIdID of the user.
displayNamestringoptionalName of the user.
emailstringEmail of the user.
devicesarray<object>AuditLogDeviceReferenceDevices.
2 fields
deviceIdstringDeviceIdID of the device.
namestringName of the device.
organizationApiTokensarray<object>AuditLogOrganizationApiTokenReferenceOrganization API tokens.
2 fields
tokenIdstringOrganizationApiTokenIdID of the API token.
namestringName of the API token.
Example
curl --fail-with-body \
-H "Authorization: Bearer $NEXIGON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"deviceId":"<device-id>"}' \
$NEXIGON_HUB_URL/api/v1/actions/invoke/devices_QueryAuditLog{
"events": [
{
"eventId": "<audit-log-event-id>",
"actor": {
"actor": "Device",
"deviceId": "<device-id>",
"tokenId": "<deployment-token-id>"
},
"event": "<event>",
"data": {},
"createdAt": "2026-01-01T12:00:00Z"
}
]
}devices_QueryCommands
POST/api/v1/actions/invoke/devices_QueryCommands
- Unstable (feature
device_commands)
Query the on-demand commands supported by a device.
Request QueryDeviceCommandsAction
deviceIdstringDeviceIdID of the device.
Response QueryDeviceCommandsOutput
manifestobjectDeviceCommandManifestCommand manifest.
1 field
commandsarray<object>DeviceCommandDescriptorAvailable commands.
5 fields
namestringCommand name.
descriptionstringoptionalDescription of what the command does.
categorystringoptionalCategory for grouping in the UI.
inputanyJsonValueoptionalJSON Schema for the command input.
outputanyJsonValueoptionalJSON Schema for the command output.
Example
curl --fail-with-body \
-H "Authorization: Bearer $NEXIGON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"deviceId":"<device-id>"}' \
$NEXIGON_HUB_URL/api/v1/actions/invoke/devices_QueryCommands{
"manifest": {
"commands": [
{
"name": "<name>"
}
]
}
}devices_UpdateGroups
POST/api/v1/actions/invoke/devices_UpdateGroups
Atomically add and remove memberships on explicit devices in one project.
Adding an existing membership or removing an absent one is a no-op. A group cannot appear in both lists. Unrelated memberships are preserved. All devices and groups must belong to the project; otherwise no memberships change. Device credentials cannot change groups. Removing a membership does not cancel work that an operation has already assigned to the device.
Request UpdateDeviceGroupsAction
projectIdstringProjectIddeviceIdsarray<string>DeviceId- Select at least one device.
addarray<string>DeviceGroupIdremovearray<string>DeviceGroupId
Response Empty
No fields. The response is an empty JSON object.
Example
curl --fail-with-body \
-H "Authorization: Bearer $NEXIGON_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"projectId": "<project-id>",
"deviceIds": [
"<device-id>"
],
"add": [
"<device-group-id>"
],
"remove": [
"<device-group-id>"
]
}' \
$NEXIGON_HUB_URL/api/v1/actions/invoke/devices_UpdateGroups{}devices_SetProfiles
POST/api/v1/actions/invoke/devices_SetProfiles
- Unstable (feature
device_profiles)
Replace the profiles of a device.
The device applies the profiles in the given order, so later profiles take precedence. Device credentials cannot change profiles.
Request SetDeviceProfilesAction
deviceIdstringDeviceIdprofilesarray<object>DeviceProfileAssignmentProfiles of the device and their modes, in the order they apply. A profile may appear only once.
2 fields
profileIdstringDeviceProfileIdmodeobjectDeviceProfileModeoptionalDefaults to
Latest.3 variants
One of the following, identified by
mode:mode: "Latest"Use every revision as soon as it is saved.
mode: "Pinned"Use one specific revision.
revisioninteger
mode: "Rollout"Use the revision of the profile's rollout once the rollout reaches the device. The device then applies the revision, even if it already uses it.
A device that switches to this mode keeps its current revision until then. A device that gets the profile in this mode has no revision until then, so that the profile sets no values on it.
Response Empty
No fields. The response is an empty JSON object.
Example
curl --fail-with-body \
-H "Authorization: Bearer $NEXIGON_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"deviceId": "<device-id>",
"profiles": [
{
"profileId": "<device-profile-id>"
}
]
}' \
$NEXIGON_HUB_URL/api/v1/actions/invoke/devices_SetProfiles{}devices_UpdateProfiles
POST/api/v1/actions/invoke/devices_UpdateProfiles
- Unstable (feature
device_profiles)
Atomically add and remove profiles on explicit devices in one project.
Added profiles apply after the device's other profiles, in the given order. Adding an assigned profile keeps its position but sets its mode, and removing an absent one is a no-op. A profile cannot appear in both lists. All devices and profiles must belong to the project; otherwise no assignments change. Device credentials cannot change profiles.
Request UpdateDeviceProfilesAction
projectIdstringProjectIddeviceIdsarray<string>DeviceId- Select at least one device.
addarray<object>DeviceProfileAssignmentProfiles to add with their modes, in the order they apply after a device's other profiles.
2 fields
profileIdstringDeviceProfileIdmodeobjectDeviceProfileModeoptionalDefaults to
Latest.3 variants
One of the following, identified by
mode:mode: "Latest"Use every revision as soon as it is saved.
mode: "Pinned"Use one specific revision.
revisioninteger
mode: "Rollout"Use the revision of the profile's rollout once the rollout reaches the device. The device then applies the revision, even if it already uses it.
A device that switches to this mode keeps its current revision until then. A device that gets the profile in this mode has no revision until then, so that the profile sets no values on it.
removearray<string>DeviceProfileIdProfiles to remove.
Response Empty
No fields. The response is an empty JSON object.
Example
curl --fail-with-body \
-H "Authorization: Bearer $NEXIGON_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"projectId": "<project-id>",
"deviceIds": [
"<device-id>"
],
"add": [
{
"profileId": "<device-profile-id>"
}
],
"remove": [
"<device-profile-id>"
]
}' \
$NEXIGON_HUB_URL/api/v1/actions/invoke/devices_UpdateProfiles{}devices_QueryOperations
POST/api/v1/actions/invoke/devices_QueryOperations
Query device operations for a device.
Request QueryDeviceOperationsAction
deviceIdstringDeviceIdID of the device.
Response QueryDeviceOperationsOutput
operationsarray<object>DeviceOperationSummaryDevice operations.
15 fields
deviceOperationIdstringDeviceOperationIdID of the operation.
projectIdstringProjectIdProject the device belongs to.
deviceIdstringDeviceIdDevice the operation is bound to.
createdByobjectActoroptionalActor that created the operation.
For an operation created directly against a device, this is whoever created it. For one belonging to a fleet operation, it is whoever created that, since the rollout is what caused the work to exist. Either way it answers "who is responsible for this device doing this", which is what a reader of a device's history wants to know.
7 variants
One of the following, identified by
actor:actor: "Anonymous"An anonymous, unauthenticated actor.
actor: "System"The system itself, typically used for internal actions.
actor: "Device"A device authenticated via a specific deployment token.
deviceIdstringDeviceIdID of the device.
tokenIdstringDeploymentTokenIdID of the deployment token used for authentication.
actor: "User"A user typically authenticated via a user session.
userIdstringUserIdID of the user.
actor: "UserToken"A user authenticated via a specific token.
userIdstringUserIdID of the user.
tokenIdstringUserTokenIdID of the user token used for authentication.
actor: "ClusterNode"A cluster node.
nodeIdstringClusterNodeIdID of the cluster node.
actor: "OrganizationApiToken"An organization API token.
organizationIdstringOrganizationIdID of the organization.
tokenIdstringOrganizationApiTokenIdID of the API token.
fleetOperationIdstringFleetOperationIdoptionalFleet operation that materialized this operation, if any.
Absent for operations created directly against the device.
namestringOperation name.
A standalone device operation owns this name. A fleet-owned device operation inherits it from its fleet operation.
descriptionstringoptionalOptional description.
statusstringDeviceOperationStatusLifecycle status.
"Pending"Operation is ready but has not started executing steps.
"Running"Operation is currently applying steps.
"Succeeded"Operation completed all steps.
"Failed"Operation failed a step.
"TimedOut"Operation exceeded a step's timeout or its deadline.
"Cancelled"Operation was cancelled.
stepIndexintegerCurrent step index.
stepCountintegerNumber of configured steps.
lastErrorstringoptionalLast step or operation error.
createdAtstring (date-time)TimestampCreation time.
startedAtstring (date-time)TimestampoptionalStart time.
completedAtstring (date-time)TimestampoptionalCompletion time.
updatedAtstring (date-time)TimestampLast update time.
Example
curl --fail-with-body \
-H "Authorization: Bearer $NEXIGON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"deviceId":"<device-id>"}' \
$NEXIGON_HUB_URL/api/v1/actions/invoke/devices_QueryOperations{
"operations": [
{
"deviceOperationId": "<device-operation-id>",
"projectId": "<project-id>",
"deviceId": "<device-id>",
"name": "<name>",
"status": "Pending",
"stepIndex": 1,
"stepCount": 1,
"createdAt": "2026-01-01T12:00:00Z",
"updatedAt": "2026-01-01T12:00:00Z"
}
]
}devices_GetOperation
POST/api/v1/actions/invoke/devices_GetOperation
Get device operation details.
Request GetDeviceOperationAction
deviceOperationIdstringDeviceOperationIdID of the operation.
Response GetDeviceOperationOutput
One of the following, identified by result:
result: "NotFound"Operation was not found or the actor cannot access it.
result: "Found"Operation was found.
summaryobjectDeviceOperationSummarySummary.
15 fields
deviceOperationIdstringDeviceOperationIdID of the operation.
projectIdstringProjectIdProject the device belongs to.
deviceIdstringDeviceIdDevice the operation is bound to.
createdByobjectActoroptionalActor that created the operation.
For an operation created directly against a device, this is whoever created it. For one belonging to a fleet operation, it is whoever created that, since the rollout is what caused the work to exist. Either way it answers "who is responsible for this device doing this", which is what a reader of a device's history wants to know.
7 variants
One of the following, identified by
actor:actor: "Anonymous"An anonymous, unauthenticated actor.
actor: "System"The system itself, typically used for internal actions.
actor: "Device"A device authenticated via a specific deployment token.
deviceIdstringDeviceIdID of the device.
tokenIdstringDeploymentTokenIdID of the deployment token used for authentication.
actor: "User"A user typically authenticated via a user session.
userIdstringUserIdID of the user.
actor: "UserToken"A user authenticated via a specific token.
userIdstringUserIdID of the user.
tokenIdstringUserTokenIdID of the user token used for authentication.
actor: "ClusterNode"A cluster node.
nodeIdstringClusterNodeIdID of the cluster node.
actor: "OrganizationApiToken"An organization API token.
organizationIdstringOrganizationIdID of the organization.
tokenIdstringOrganizationApiTokenIdID of the API token.
fleetOperationIdstringFleetOperationIdoptionalFleet operation that materialized this operation, if any.
Absent for operations created directly against the device.
namestringOperation name.
A standalone device operation owns this name. A fleet-owned device operation inherits it from its fleet operation.
descriptionstringoptionalOptional description.
statusstringDeviceOperationStatusLifecycle status.
"Pending"Operation is ready but has not started executing steps.
"Running"Operation is currently applying steps.
"Succeeded"Operation completed all steps.
"Failed"Operation failed a step.
"TimedOut"Operation exceeded a step's timeout or its deadline.
"Cancelled"Operation was cancelled.
stepIndexintegerCurrent step index.
stepCountintegerNumber of configured steps.
lastErrorstringoptionalLast step or operation error.
createdAtstring (date-time)TimestampCreation time.
startedAtstring (date-time)TimestampoptionalStart time.
completedAtstring (date-time)TimestampoptionalCompletion time.
updatedAtstring (date-time)TimestampLast update time.
stepsarray<object>DeviceOperationStepOrdered steps.
5 variants
One of the following, identified by
kind:kind: "SetDeviceProperty"Set the device's own value of a property.
whenstringoptionalExpression that decides whether the step runs. A step whose expression is false is skipped, and a step whose expression produces an error fails. Without an expression, the step runs.
- Expressions must be at most 4096 characters.
namestringProperty name.
- Property name must be between 1 and 256 characters.
- Property name must start with a letter or digit and contain only letters, digits, dots, underscores, or hyphens.
valueanyJsonValueValue to set.
Nexigon Hub rejects values larger than the instance's limit, 64 KiB by default.
protectedbooleanoptionalWhether the property is protected. Defaults to
false.
kind: "PatchDeviceProperty"Apply a JSON merge patch to the device's own value of a property.
whenstringoptionalExpression that decides whether the step runs. A step whose expression is false is skipped, and a step whose expression produces an error fails. Without an expression, the step runs.
- Expressions must be at most 4096 characters.
namestringProperty name.
- Property name must be between 1 and 256 characters.
- Property name must start with a letter or digit and contain only letters, digits, dots, underscores, or hyphens.
patchanyJsonValuePatch to apply. Without an own value, the patch applies to
null.Nexigon Hub rejects patches larger than the instance's limit for property values, 64 KiB by default. A step fails if the resulting value exceeds the limit.
protectedbooleanoptionalWhether the property is protected. Without this field, a property keeps its protection, and a new property is unprotected.
kind: "RemoveDeviceProperty"Remove the device's own value of a property.
whenstringoptionalExpression that decides whether the step runs. A step whose expression is false is skipped, and a step whose expression produces an error fails. Without an expression, the step runs.
- Expressions must be at most 4096 characters.
namestringProperty name.
- Property name must be between 1 and 256 characters.
- Property name must start with a letter or digit and contain only letters, digits, dots, underscores, or hyphens.
kind: "DeviceCommand"Ask the device to run a command.
whenstringoptionalExpression that decides whether the step runs. A step whose expression is false is skipped, and a step whose expression produces an error fails. Without an expression, the step runs.
- Expressions must be at most 4096 characters.
commandstringCommand name from the device command manifest.
- Command name must be between 1 and 256 characters.
inputanyJsonValueCommand input.
Nexigon Hub rejects inputs larger than the instance's limit, 64 KiB by default.
timeoutSecsintegeroptionalTime that the device has to run the command, in seconds. Defaults to one hour.
The time starts when the device claims the command, and the device passes it to the command handler as its execution timeout. Use a fleet operation's deadline to limit the wait for an offline device.
- Command timeout must be between 1 second and 1 day.
kind: "WaitForDeviceProperty"Wait until the device's properties satisfy an expression.
whenstringoptionalExpression that decides whether the step runs. A step whose expression is false is skipped, and a step whose expression produces an error fails. Without an expression, the step runs.
- Expressions must be at most 4096 characters.
expressionstringExpression that finishes the wait once it is true.
- Expressions must be between 1 and 4096 characters.
failureExpressionstringoptionalExpression that fails the step once it is true. It takes precedence over
expression.- Expressions must be at most 4096 characters.
timeoutSecsintegeroptionalTime to wait, in seconds, after which the step times out. Without it, the step waits until a fleet operation's deadline, if any, or until the operation is cancelled.
- Wait timeout must be between 1 second and 30 days.
stepStatesarray<object>DeviceOperationStepStateState for steps that have started, one entry per step reached so far.
A step with no entry here has not been reached yet. Correlate entries with
stepsbystep_index, not array position or length β this list isn't guaranteed to stay dense or gapless as a matter of API contract, even though the current driver happens to fill it in strictly in order.7 fields
stepIndexintegerIndex into
DeviceOperationDetails.stepsof the step this state is for.statusstringDeviceOperationStepStatusStep execution status.
"Pending"Step has not been started.
"Running"Step is waiting for the device or for its expression.
"Succeeded"Step succeeded.
"Failed"Step failed.
"TimedOut"Step exceeded its timeout or the operation's deadline.
"Skipped"Step was skipped by conditions.
outputanyJsonValueoptionalOutput that the device reported for a command.
omittedOutputBytesinteger (64-bit)optionalSize in bytes of the output that the device reported for a command, if the output exceeded the instance's limit. Nexigon Hub then stores only the size.
errorstringoptionalError message when the step failed or timed out, or the latest error of a waiting step's expressions.
startedAtstring (date-time)TimestampoptionalWhen the step started running.
completedAtstring (date-time)TimestampoptionalWhen the step reached a terminal status.
Example
curl --fail-with-body \
-H "Authorization: Bearer $NEXIGON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"deviceOperationId":"<device-operation-id>"}' \
$NEXIGON_HUB_URL/api/v1/actions/invoke/devices_GetOperation{
"result": "Found",
"summary": {
"deviceOperationId": "<device-operation-id>",
"projectId": "<project-id>",
"deviceId": "<device-id>",
"name": "<name>",
"status": "Pending",
"stepIndex": 1,
"stepCount": 1,
"createdAt": "2026-01-01T12:00:00Z",
"updatedAt": "2026-01-01T12:00:00Z"
},
"steps": [
{
"kind": "SetDeviceProperty",
"name": "<name>",
"value": {}
}
],
"stepStates": [
{
"stepIndex": 1,
"status": "Pending"
}
]
}devices_CreateOperation
POST/api/v1/actions/invoke/devices_CreateOperation
Create a device operation.
Request CreateDeviceOperationAction
deviceIdstringDeviceIdDevice the operation is bound to.
namestringOperation name.
- Device operation name must be between 1 and 128 characters.
descriptionstringoptionalOptional description.
- Device operation description must be at most 4096 characters.
stepsarray<object>DeviceOperationStepOrdered steps.
5 variants
One of the following, identified by
kind:kind: "SetDeviceProperty"Set the device's own value of a property.
whenstringoptionalExpression that decides whether the step runs. A step whose expression is false is skipped, and a step whose expression produces an error fails. Without an expression, the step runs.
- Expressions must be at most 4096 characters.
namestringProperty name.
- Property name must be between 1 and 256 characters.
- Property name must start with a letter or digit and contain only letters, digits, dots, underscores, or hyphens.
valueanyJsonValueValue to set.
Nexigon Hub rejects values larger than the instance's limit, 64 KiB by default.
protectedbooleanoptionalWhether the property is protected. Defaults to
false.
kind: "PatchDeviceProperty"Apply a JSON merge patch to the device's own value of a property.
whenstringoptionalExpression that decides whether the step runs. A step whose expression is false is skipped, and a step whose expression produces an error fails. Without an expression, the step runs.
- Expressions must be at most 4096 characters.
namestringProperty name.
- Property name must be between 1 and 256 characters.
- Property name must start with a letter or digit and contain only letters, digits, dots, underscores, or hyphens.
patchanyJsonValuePatch to apply. Without an own value, the patch applies to
null.Nexigon Hub rejects patches larger than the instance's limit for property values, 64 KiB by default. A step fails if the resulting value exceeds the limit.
protectedbooleanoptionalWhether the property is protected. Without this field, a property keeps its protection, and a new property is unprotected.
kind: "RemoveDeviceProperty"Remove the device's own value of a property.
whenstringoptionalExpression that decides whether the step runs. A step whose expression is false is skipped, and a step whose expression produces an error fails. Without an expression, the step runs.
- Expressions must be at most 4096 characters.
namestringProperty name.
- Property name must be between 1 and 256 characters.
- Property name must start with a letter or digit and contain only letters, digits, dots, underscores, or hyphens.
kind: "DeviceCommand"Ask the device to run a command.
whenstringoptionalExpression that decides whether the step runs. A step whose expression is false is skipped, and a step whose expression produces an error fails. Without an expression, the step runs.
- Expressions must be at most 4096 characters.
commandstringCommand name from the device command manifest.
- Command name must be between 1 and 256 characters.
inputanyJsonValueCommand input.
Nexigon Hub rejects inputs larger than the instance's limit, 64 KiB by default.
timeoutSecsintegeroptionalTime that the device has to run the command, in seconds. Defaults to one hour.
The time starts when the device claims the command, and the device passes it to the command handler as its execution timeout. Use a fleet operation's deadline to limit the wait for an offline device.
- Command timeout must be between 1 second and 1 day.
kind: "WaitForDeviceProperty"Wait until the device's properties satisfy an expression.
whenstringoptionalExpression that decides whether the step runs. A step whose expression is false is skipped, and a step whose expression produces an error fails. Without an expression, the step runs.
- Expressions must be at most 4096 characters.
expressionstringExpression that finishes the wait once it is true.
- Expressions must be between 1 and 4096 characters.
failureExpressionstringoptionalExpression that fails the step once it is true. It takes precedence over
expression.- Expressions must be at most 4096 characters.
timeoutSecsintegeroptionalTime to wait, in seconds, after which the step times out. Without it, the step waits until a fleet operation's deadline, if any, or until the operation is cancelled.
- Wait timeout must be between 1 second and 30 days.
Response CreateDeviceOperationOutput
deviceOperationIdstringDeviceOperationIdID of the created operation.
Example
curl --fail-with-body \
-H "Authorization: Bearer $NEXIGON_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"deviceId": "<device-id>",
"name": "<name>",
"steps": [
{
"kind": "SetDeviceProperty",
"name": "<name>",
"value": {}
}
]
}' \
$NEXIGON_HUB_URL/api/v1/actions/invoke/devices_CreateOperation{
"deviceOperationId": "<device-operation-id>"
}devices_StartOperation
POST/api/v1/actions/invoke/devices_StartOperation
Start a pending device operation.
Request StartDeviceOperationAction
deviceOperationIdstringDeviceOperationIdID of the operation.
Response Empty
No fields. The response is an empty JSON object.
Example
curl --fail-with-body \
-H "Authorization: Bearer $NEXIGON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"deviceOperationId":"<device-operation-id>"}' \
$NEXIGON_HUB_URL/api/v1/actions/invoke/devices_StartOperation{}devices_CancelOperation
POST/api/v1/actions/invoke/devices_CancelOperation
Cancel a device operation.
Request CancelDeviceOperationAction
deviceOperationIdstringDeviceOperationIdID of the operation.
Response Empty
No fields. The response is an empty JSON object.
Example
curl --fail-with-body \
-H "Authorization: Bearer $NEXIGON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"deviceOperationId":"<device-operation-id>"}' \
$NEXIGON_HUB_URL/api/v1/actions/invoke/devices_CancelOperation{}devices_ClaimOperationWork
POST/api/v1/actions/invoke/devices_ClaimOperationWorkDevice API
Claim device operation work for a device.
Leases pending work items to the device atomically, so no other worker receives
them at the same time. Report the outcome of each item with
devices_ReportOperationStep, passing the item's claim ID. Only the device itself
can claim its work.
Request ClaimDeviceOperationWorkAction
deviceIdstringDeviceIdID of the device claiming work.
limitintegeroptionalMaximum number of work items to claim. Defaults to 1.
- Claim limit must be between 1 and 20.
kindsarray<string>DeviceOperationWorkKindoptionalWork kinds to return. Defaults to all device-executable work.
"DeviceCommand"Command work, which Nexigon Agent runs with its device commands.
Response ClaimDeviceOperationWorkOutput
workarray<object>DeviceOperationWorkItemWork items leased to the device.
5 fields
deviceOperationIdstringDeviceOperationIdID of the device operation the work belongs to.
claimIdstringDeviceOperationWorkClaimIdClaim that must accompany reports for this delivery of the work.
A later poll after the lease expires replaces this claim, fencing reports from the older worker.
operationNamestringName of the standalone or fleet operation that defined this work.
stepIndexintegerZero-based index of the step within the device operation. Pass it to
devices_ReportOperationStepwith the claim.stepobjectDeviceOperationWorkStepStep to run.
1 variant
One of the following, identified by
kind:kind: "DeviceCommand"Run an on-device command and report its result.
commandstringCommand name from the device command manifest.
inputanyJsonValueCommand input.
timeoutSecsintegeroptionalExecution timeout of the command handler, in seconds. Defaults to one hour.
Example
curl --fail-with-body \
-H "Authorization: Bearer $NEXIGON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"deviceId":"<device-id>"}' \
$NEXIGON_HUB_URL/api/v1/actions/invoke/devices_ClaimOperationWork{
"work": [
{
"deviceOperationId": "<device-operation-id>",
"claimId": "<device-operation-work-claim-id>",
"operationName": "<operation-name>",
"stepIndex": 1,
"step": {
"kind": "DeviceCommand",
"command": "<command>",
"input": {}
}
}
]
}devices_ReportOperationStep
POST/api/v1/actions/invoke/devices_ReportOperationStepDevice API
Report the result of a device operation step.
Repeating a report after it was already applied is a successful no-op. A report whose claim has been superseded is also ignored, so an expired worker cannot overwrite the current attempt.
Request ReportDeviceOperationStepAction
deviceIdstringDeviceIdID of the reporting device.
deviceOperationIdstringDeviceOperationIdID of the operation.
stepIndexintegerStep index being reported.
claimIdstringDeviceOperationWorkClaimIdClaim returned by the poll that delivered this work item.
reportobjectDeviceOperationStepReportReported step outcome.
3 fields
statusstringDeviceOperationStepReportStatusResult status.
"Succeeded"Step succeeded.
"Failed"Step failed.
outputanyJsonValueoptionalCommand output.
Nexigon Hub stores outputs up to the instance's limit, 64 KiB by default, and only the size of larger outputs.
errorstringoptionalError message when the step failed.
- Error message must be at most 4096 characters.
Response Empty
No fields. The response is an empty JSON object.
Example
curl --fail-with-body \
-H "Authorization: Bearer $NEXIGON_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"deviceId": "<device-id>",
"deviceOperationId": "<device-operation-id>",
"stepIndex": 1,
"claimId": "<device-operation-work-claim-id>",
"report": {
"status": "Succeeded"
}
}' \
$NEXIGON_HUB_URL/api/v1/actions/invoke/devices_ReportOperationStep{}