Devices API

Actions in the devices namespace of the Nexigon Hub API.

`devices_Query`

POST/api/v1/actions/invoke/devices_Query

Query the devices of the instance.

Request QueryDevicesAction

No fields.

Response QueryDevicesOutput

Fields (JSON object)

devicesrequired
List of devices.
array<QueryDevicesItem>
Items
QueryDevicesItem
Fields (JSON object)
deviceId(from device_id)required
ID of the device.

DeviceIdstring
projectId(from project_id)required
Project ID of the device.

ProjectIdstring
isConnected(from is_connected)required
Indicates whether the device is currently connected.

boolean
lastConnectedAt(from last_connected_at)optional
Timestamp when the device was last connected (current or most recent connection).

Timestampstring
currentConnectionDurationSecs(from current_connection_duration_secs)optional
Duration of the current connection in seconds (null if not connected).

integer

`devices_GetDetails`

POST/api/v1/actions/invoke/devices_GetDetails

Get information about a device.

Request GetDeviceDetailsAction

Fields (JSON object)

deviceId(from device_id)required
ID of the device.

DeviceIdstring

Response GetDeviceDetailsOutput

Fields (JSON object)

deviceId(from device_id)required
ID of the device.

DeviceIdstring
projectId(from project_id)required
Project ID of the device.

ProjectIdstring
fingerprintId(from fingerprint_id)required
Fingerprint ID the device.

DeviceFingerprintIdstring
nameoptional
Name of the device.

string
isConnected(from is_connected)required
Indicates whether the device is online.

boolean
certificatesrequired
Certificates of the device.
array<DeviceCertificate>
Items
DeviceCertificate
Fields (JSON object)
certificateId(from certificate_id)required
ID of the certificate.

DeviceCertificateIdstring
statusrequired
Status of the certificate.

DeviceCertificateStatus
Casesexternally
Pending
The certificate is pending.

Value: "Pending"
Active
The certificate is active.

Value: "Active"
Rejected
The certificate has been rejected.

Value: "Rejected"
Revoked
The certificate has been revoked.

Value: "Revoked"
Conflict
The certificate fingerprint was seen on multiple devices.

Value: "Conflict"
fingerprintrequired
Fingerprint of the certificate.

CertificateFingerprintstring
firstSeen(from first_seen)required
Timestamp when the certificate was first seen.

Timestampstring
connectionsrequired
Connections of the device.
array<DeviceConnection>
Items
DeviceConnection
Fields (JSON object)
connectionId(from connection_id)required
ID of the connection.

DeviceConnectionIdstring
nodeId(from node_id)required
ID of the cluster node.

ClusterNodeIdstring
connectedAt(from connected_at)required
Timestamp when the connection was established.

Timestampstring
connectedForSecs(from connected_for_secs)required
Duration of the connection in seconds.

integer

`devices_Create`

POST/api/v1/actions/invoke/devices_Create

Create a new device.

Request CreateDeviceAction

Fields (JSON object)

projectId(from project_id)required
ID of the project.

ProjectIdstring
fingerprintrequired
Fingerprint of the device.

DeviceFingerprintstring

Response CreateDeviceOutput

Fields (JSON object)

deviceId(from device_id)required
ID of the device.

DeviceIdstring

`devices_Delete`

POST/api/v1/actions/invoke/devices_Delete

Delete a device.

Request DeleteDeviceAction

Fields (JSON object)

deviceId(from device_id)required
ID of the device.

DeviceIdstring

Response Empty

No fields.

`devices_SetName`

POST/api/v1/actions/invoke/devices_SetName

Set the name of a device.

Request SetDeviceNameAction

Fields (JSON object)

deviceId(from device_id)required
ID of the device.

DeviceIdstring
nameoptional
New name of the device.

string

Response Empty

No fields.

`devices_IssueDeviceToken`

POST/api/v1/actions/invoke/devices_IssueDeviceToken

Issue a JWT for a device with user-defined claims.

Note: Only use this action for integration with external systems.

Request IssueDeviceTokenAction

Fields (JSON object)

deviceId(from device_id)required
ID of the device.

DeviceIdstring
validForSecs(from valid_for_secs)optional
Token validity duration in seconds.

integer
claimsoptional
Additional user-defined claims.

JsonValueany

Response IssueDeviceTokenOutput

Fields (JSON object)

jwtrequired
Issued JWT.

Jwt
Wraps
string

`devices_ValidateDeviceToken`

POST/api/v1/actions/invoke/devices_ValidateDeviceToken

Validate a device JWT.

Note: Only use this action for integration with external systems.

Request ValidateDeviceTokenAction

Fields (JSON object)

jwtrequired
JWT to validate.

Jwt
Wraps
string

Response ValidateDeviceTokenOutput

Casesinternally — tag field result

Invalid
The JWT is invalid.

{ "result": "Invalid" }
Valid
The JWT is valid.

{ "result": "Valid", ...<payload fields> } — or "content" for non-object payloads
ValidateDeviceTokenSuccess
Fields (JSON object)
deviceId(from device_id)required
ID of the device.

DeviceIdstring
claimsrequired
User-defined claims.

JsonValueany

`devices_AddCertificate`

POST/api/v1/actions/invoke/devices_AddCertificate

Add a device certificate.

Request AddDeviceCertificateAction

Fields (JSON object)

deviceId(from device_id)required
ID of the device.

DeviceIdstring
fingerprintrequired
Fingerprint of the certificate.

CertificateFingerprintstring
statusoptional
Initial status of the certificate.

Defaults to Pending.
DeviceCertificateStatus
Casesexternally
Pending
The certificate is pending.

Value: "Pending"
Active
The certificate is active.

Value: "Active"
Rejected
The certificate has been rejected.

Value: "Rejected"
Revoked
The certificate has been revoked.

Value: "Revoked"
Conflict
The certificate fingerprint was seen on multiple devices.

Value: "Conflict"

Response AddDeviceCertificateOutput

Fields (JSON object)

certificateId(from certificate_id)required
ID of the certificate.

DeviceCertificateIdstring

`devices_DeleteCertificate`

POST/api/v1/actions/invoke/devices_DeleteCertificate

Delete a device certificate.

Request DeleteDeviceCertificateAction

Fields (JSON object)

certificateId(from certificate_id)required
ID of the certificate.

DeviceCertificateIdstring

Response Empty

No fields.

`devices_SetCertificateStatus`

POST/api/v1/actions/invoke/devices_SetCertificateStatus

Set the status of a device certificate.

Request SetDeviceCertificateStatusAction

Fields (JSON object)

certificateId(from certificate_id)required
ID of the certificate.

DeviceCertificateIdstring
statusrequired
New status of the certificate.
DeviceCertificateStatus
Casesexternally
Pending
The certificate is pending.

Value: "Pending"
Active
The certificate is active.

Value: "Active"
Rejected
The certificate has been rejected.

Value: "Rejected"
Revoked
The certificate has been revoked.

Value: "Revoked"
Conflict
The certificate fingerprint was seen on multiple devices.

Value: "Conflict"

Response Empty

No fields.

`devices_RegisterConnection`

POST/api/v1/actions/invoke/devices_RegisterConnection

Request RegisterDeviceConnectionAction

Fields (JSON object)

deviceId(from device_id)required
ID of the device.

DeviceIdstring
nodeId(from node_id)required
ID of the cluster node.

ClusterNodeIdstring
connectionId(from connection_id)required
Pre-generated ID of the connection.

DeviceConnectionIdstring

Response RegisterDeviceConnectionOutput

Fields (JSON object)

connectionId(from connection_id)required
ID of the connection.

DeviceConnectionIdstring

`devices_UnregisterConnection`

POST/api/v1/actions/invoke/devices_UnregisterConnection

Unregister a connection of a device to a cluster node.

Request UnregisterDeviceConnectionAction

Fields (JSON object)

connectionId(from connection_id)required
ID of the connection.

DeviceConnectionIdstring
endReason(from end_reason)required
Reason for ending the connection.
ConnectionEndReason
Casesexternally
Unknown
Unknown reason (fallback).

Value: "Unknown"
Disconnected
Device disconnected normally.

Value: "Disconnected"
NodeCrashed
Connection ended due to cluster node crash or heartbeat timeout.

Value: "NodeCrashed"
ServerShutdown
Connection ended due to graceful server shutdown.

Value: "ServerShutdown"

Response Empty

No fields.

`devices_QueryConnections`

POST/api/v1/actions/invoke/devices_QueryConnections

Query the connection history of a device.

Request QueryDeviceConnectionsAction

Fields (JSON object)

deviceId(from device_id)required
ID of the device.

DeviceIdstring
limitoptional
Limit results (default 100).

integer
activeOnly(from active_only)optional
Include only active connections.

boolean

Response QueryDeviceConnectionsOutput

Fields (JSON object)

connectionsrequired
List of connections.
array<DeviceConnectionLog>
Items
DeviceConnectionLog
Fields (JSON object)
connectionId(from connection_id)required
ID of the connection.

DeviceConnectionIdstring
nodeId(from node_id)required
ID of the cluster node.

ClusterNodeIdstring
connectedAt(from connected_at)required
Timestamp when the connection was established.

Timestampstring
endedAt(from ended_at)optional
Timestamp when the connection ended (null if still connected).

Timestampstring
endReason(from end_reason)optional
Reason why the connection ended (null if still connected).

ConnectionEndReason
Casesexternally
Unknown
Unknown reason (fallback).

Value: "Unknown"
Disconnected
Device disconnected normally.

Value: "Disconnected"
NodeCrashed
Connection ended due to cluster node crash or heartbeat timeout.

Value: "NodeCrashed"
ServerShutdown
Connection ended due to graceful server shutdown.

Value: "ServerShutdown"
durationSecs(from duration_secs)required
Duration of the connection in seconds.

integer

`devices_IssueHttpProxyToken`

POST/api/v1/actions/invoke/devices_IssueHttpProxyToken

Issue a HTTP proxy JWT.

Request IssueDeviceHttpProxyTokenAction

Fields (JSON object)

deviceId(from device_id)required
ID of the device.

DeviceIdstring
validForSecs(from valid_for_secs)optional
Token validity duration in seconds.

integer
hostnameoptional
Hostname to accept requests for.

Defaults to a device-specific pseudo-random subdomain of the instance domain.

string
portoptional
Device port to proxy to.

Defaults to 80.

integer
redirectoptional
Redirect URL in case the token is expired or invalid.

string

Response IssueDeviceHttpProxyTokenOutput

Fields (JSON object)

jwtrequired
JWT proxy token.

Jwt
Wraps
string
urlrequired
Proxy URL.

string

`devices_ValidateHttpProxyToken`

POST/api/v1/actions/invoke/devices_ValidateHttpProxyToken

Validate a HTTP proxy JWT.

Request ValidateDeviceHttpProxyTokenAction

Fields (JSON object)

jwtrequired
JWT to validate.

Jwt
Wraps
string

Response ValidateDeviceHttpProxyTokenOutput

Casesinternally — tag field result

Invalid
The JWT is invalid.

{ "result": "Invalid", ...<payload fields> } — or "content" for non-object payloads
ValidateDeviceHttpProxyTokenInvalid
Fields (JSON object)
redirectoptional
URL to redirect to.

string
Valid
The JWT is valid.

{ "result": "Valid", ...<payload fields> } — or "content" for non-object payloads
ValidateDeviceHttpProxyTokenSuccess
Fields (JSON object)
deviceId(from device_id)required
ID of the device.

DeviceIdstring
hostnameoptional
Hostname to accept requests for.

string
portoptional
Device port to proxy to.

integer

`devices_PublishEvents`

POST/api/v1/actions/invoke/devices_PublishEvents

Publish device events.

Request PublishDeviceEventsAction

Fields (JSON object)

deviceId(from device_id)required
ID of the device.

DeviceIdstring
eventsrequired
Events to push.
array<DeviceEvent>
Items
DeviceEvent
Fields (JSON object)
eventId(from event_id)required
ID of the event.

DeviceEventIdstring
categoryoptional
Event category (optional, low-cardinality category of the event).

string
severityrequired
Severity of the event.

DeviceEventSeverity
Casesexternally
Trace
Tracing event.

Value: "Trace"
Debug
Debugging event.

Value: "Debug"
Info
Informational even.

Value: "Info"
Warning
Warning event.

Value: "Warning"
Error
Error event.

Value: "Error"
Critical
Critical event.

Value: "Critical"
bodyrequired
Event body.

JsonValueany
attributesrequired
Event attributes.

object<string, JsonValue>
Keys
string
Values
JsonValueany
emittedAt(from emitted_at)required
Timestamp when the event was emitted.

Timestampstring
receivedAt(from received_at)optional
Timestamp when the event was received.

Timestampstring

Response Empty

No fields.

`devices_QueryEvents`

POST/api/v1/actions/invoke/devices_QueryEvents

Query device events.

Request QueryDeviceEventsAction

Fields (JSON object)

deviceId(from device_id)required
ID of the device.

DeviceIdstring
limitoptional
Limit the number of events to return.

Default to 100.

integer

Response QueryDeviceEventsOutput

Fields (JSON object)

eventsrequired
List of events.
array<DeviceEvent>
Items
DeviceEvent
Fields (JSON object)
eventId(from event_id)required
ID of the event.

DeviceEventIdstring
categoryoptional
Event category (optional, low-cardinality category of the event).

string
severityrequired
Severity of the event.

DeviceEventSeverity
Casesexternally
Trace
Tracing event.

Value: "Trace"
Debug
Debugging event.

Value: "Debug"
Info
Informational even.

Value: "Info"
Warning
Warning event.

Value: "Warning"
Error
Error event.

Value: "Error"
Critical
Critical event.

Value: "Critical"
bodyrequired
Event body.

JsonValueany
attributesrequired
Event attributes.

object<string, JsonValue>
Keys
string
Values
JsonValueany
emittedAt(from emitted_at)required
Timestamp when the event was emitted.

Timestampstring
receivedAt(from received_at)optional
Timestamp when the event was received.

Timestampstring

`devices_SetProperty`

POST/api/v1/actions/invoke/devices_SetProperty

Set a property of a device.

Request SetDevicePropertyAction

Fields (JSON object)

deviceId(from device_id)required
ID of the device.

DeviceIdstring
namerequired
Name of the property.

string
valuerequired
Value of the property.

JsonValueany
protectedoptional
Indicates whether the property should be protected.

boolean
expectedVersion(from expected_version)optional
If set, the property is only updated when its current version matches this value (compare-and-swap). Returns VersionConflict when the version does not match, or Deleted when the property no longer exists.

integer (i64)

Response SetDevicePropertyOutput

Casesinternally — tag field result

Set
The property was set successfully.

{ "result": "Set" }
VersionConflict
The property was not updated because its version did not match the expected version (compare-and-swap conflict).

{ "result": "VersionConflict", ...<payload fields> } — or "content" for non-object payloads
SetDevicePropertyVersionConflict
Fields (JSON object)
currentVersion(from current_version)required
The current version of the property.

integer (i64)
Deleted
The property was not updated because it has been deleted while an expected version was specified.

{ "result": "Deleted" }

`devices_GetProperty`

POST/api/v1/actions/invoke/devices_GetProperty

Get a property of a device.

Request GetDevicePropertyAction

Fields (JSON object)

deviceId(from device_id)required
ID of the device.

DeviceIdstring
namerequired
Name of the property.

string

Response GetDevicePropertyOutput

Casesinternally — tag field result

NotFound
The property was not found.

{ "result": "NotFound" }
Found
The property was found.

{ "result": "Found", ...<payload fields> } — or "content" for non-object payloads
DeviceProperty
Fields (JSON object)
namerequired
Name of the property.

string
valuerequired
Value of the property.

JsonValueany
protectedrequired
Indicates whether the property is protected.

boolean
versionrequired
Incremental version number, incremented on each update.

integer (i64)
lastUpdated(from last_updated)required
Last time the property was updated.

Timestampstring

`devices_RemoveProperty`

POST/api/v1/actions/invoke/devices_RemoveProperty

Remove a property from a device.

Request RemoveDevicePropertyAction

Fields (JSON object)

deviceId(from device_id)required
ID of the device.

DeviceIdstring
namerequired
Name of the property.

string

Response RemoveDevicePropertyOutput

Casesinternally — tag field result

NotFound
The property was not found.

{ "result": "NotFound" }
Removed
The property was removed.

{ "result": "Removed" }

`devices_QueryProperties`

POST/api/v1/actions/invoke/devices_QueryProperties

Query the properties of a device.

Request QueryDevicePropertiesAction

Fields (JSON object)

deviceId(from device_id)required
ID of the device.

DeviceIdstring

Response QueryDevicePropertiesOutput

Fields (JSON object)

propertiesrequired
List of properties.
object<string, DeviceProperty>
Keys
string
Values
DeviceProperty
Fields (JSON object)
namerequired
Name of the property.

string
valuerequired
Value of the property.

JsonValueany
protectedrequired
Indicates whether the property is protected.

boolean
versionrequired
Incremental version number, incremented on each update.

integer (i64)
lastUpdated(from last_updated)required
Last time the property was updated.

Timestampstring

`devices_QueryAuditLog`

POST/api/v1/actions/invoke/devices_QueryAuditLog

Query the audit log of a device.

Request QueryDeviceAuditLogAction

Fields (JSON object)

deviceId(from device_id)required
ID of the device.

DeviceIdstring

Response QueryDeviceAuditLogOutput

Fields (JSON object)

eventsrequired
List of audit log events.
array<AuditLogEvent>
Items
AuditLogEvent
Fields (JSON object)
eventId(from event_id)required
ID of the audit log event.

AuditLogEventIdstring
actorrequired
Actor causing the event.

Actor
Casesinternally — tag field actor
Anonymous
An anonymous, unauthenticated actor.

{ "actor": "Anonymous", ...<payload fields> } — or "content" for non-object payloads
AnonymousActor
No fields.
System
The system itself, typically used for internal actions.

{ "actor": "System", ...<payload fields> } — or "content" for non-object payloads
SystemActor
No fields.
Device
A device authenticated via a specific deployment token.

{ "actor": "Device", ...<payload fields> } — or "content" for non-object payloads
DeviceActor
Fields (JSON object)
deviceId(from device_id)required
ID of the device.

DeviceIdstring
tokenId(from token_id)required
ID of the deployment token used for authentication.

DeploymentTokenIdstring
User
A user typically authenticated via a user session.

{ "actor": "User", ...<payload fields> } — or "content" for non-object payloads
UserActor
Fields (JSON object)
userId(from user_id)required
ID of the user.

UserIdstring
UserToken
A user authenticated via a specific token.

{ "actor": "UserToken", ...<payload fields> } — or "content" for non-object payloads
UserTokenActor
Fields (JSON object)
userId(from user_id)required
ID of the user.

UserIdstring
tokenId(from token_id)required
ID of the user token used for authentication.

UserTokenIdstring
ClusterNode
A cluster node.

{ "actor": "ClusterNode", ...<payload fields> } — or "content" for non-object payloads
ClusterNodeActor
Fields (JSON object)
nodeId(from node_id)required
ID of the cluster node.

ClusterNodeIdstring
OrganizationApiToken
An organization API token.

{ "actor": "OrganizationApiToken", ...<payload fields> } — or "content" for non-object payloads
OrganizationApiTokenActor
Fields (JSON object)
organizationId(from organization_id)required
ID of the organization.

OrganizationIdstring
tokenId(from token_id)required
ID of the API token.

OrganizationApiTokenIdstring
eventrequired
Type of the event that was recorded.

string
datarequired
Additional audit data associated with the event.

JsonValueany
createdAt(from created_at)required
Timestamp indicating when the audit log event was recorded.

Timestampstring
actionoptional
Action the event has been caused by (if any).

AuditLogEventAction
Fields (JSON object)
actionId(from action_id)required
ID of the action.

AuditLogActionIdstring
joboptional
Job the event has been caused by (if any).

AuditLogEventJob
Fields (JSON object)
jobId(from job_id)required
ID of the job.

JobIdstring

`devices_QueryCommands`

POST/api/v1/actions/invoke/devices_QueryCommands

Query the on-demand commands supported by a device.

Request QueryDeviceCommandsAction

Fields (JSON object)

deviceId(from device_id)required
ID of the device.

DeviceIdstring

Response QueryDeviceCommandsOutput

Fields (JSON object)

manifestrequired
Command manifest.
DeviceCommandManifest
Fields (JSON object)
commandsrequired
Available commands.

array<DeviceCommandDescriptor>
Items
DeviceCommandDescriptor
Fields (JSON object)
namerequired
Command name.

string
descriptionoptional
Description of what the command does.

string
categoryoptional
Category for grouping in the UI.

string
inputoptional
JSON Schema for the command input.

JsonValueany
outputoptional
JSON Schema for the command output.

JsonValueany