Skip to main content
Documentation

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

    List of devices.

    5 fields
    • deviceIdstringDeviceId

      ID of the device.

    • projectIdstringProjectId

      Project ID of the device.

    • isConnectedboolean

      Indicates whether the device is currently connected.

    • lastConnectedAtstring (date-time)Timestampoptional

      Timestamp when the device was last connected (current or most recent connection).

    • currentConnectionDurationSecsintegeroptional

      Duration 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

  • deviceIdstringDeviceId

    ID of the device.

Response GetDeviceDetailsOutput

  • groupsarray<object>DeviceGroup

    Groups currently assigned to this device.

    5 fields
    • groupIdstringDeviceGroupId
    • projectIdstringProjectId
    • namestring

      Unique within the project, ignoring case and surrounding whitespace.

    • colorstringDeviceGroupColoroptional
      • Group color must be a six-digit hexadecimal color, such as #3b82f6.
    • descriptionstringoptional
  • profilesarray<object>AssignedDeviceProfile

    Profiles assigned to this device, in the order they apply.

    3 fields
    • profileobjectDeviceProfileSummary
      6 fields
      • profileIdstringDeviceProfileId
      • projectIdstringProjectId
      • displayNamestring

        Display name, which does not have to be unique.

      • descriptionstringoptional
      • revisioninteger

        Latest revision. Devices always use the latest revision.

      • deviceCountinteger

        Number of devices the profile is assigned to.

    • modeobjectDeviceProfileMode
      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.

    • revisionintegeroptional

      Revision that the device uses. Absent if the profile is in rollout mode and its rollout has not reached the device.

  • deviceIdstringDeviceId

    ID of the device.

  • projectIdstringProjectId

    Project ID of the device.

  • fingerprintIdstringDeviceFingerprintId

    Fingerprint ID the device.

  • namestringoptional

    Name of the device.

  • isConnectedboolean

    Indicates whether the device is online.

  • lastSeenstring (date-time)Timestampoptional

    Time when the device last disconnected, or when it was created if it never connected. Unlike the connection log, it survives log retention.

  • certificatesarray<object>DeviceCertificate

    Certificates of the device.

    4 fields
    • certificateIdstringDeviceCertificateId

      ID of the certificate.

    • statusstringDeviceCertificateStatus

      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.

    • fingerprintstringCertificateFingerprint

      Fingerprint of the certificate.

    • firstSeenstring (date-time)Timestamp

      Timestamp when the certificate was first seen.

  • connectionsarray<object>DeviceConnection

    Connections of the device.

    4 fields
    • connectionIdstringDeviceConnectionId

      ID of the connection.

    • nodeIdstringClusterNodeId

      ID of the cluster node.

    • connectedAtstring (date-time)Timestamp

      Timestamp when the connection was established.

    • connectedForSecsinteger

      Duration 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

  • projectIdstringProjectId

    ID of the project.

  • fingerprintstringDeviceFingerprint

    Fingerprint of the device.

Response CreateDeviceOutput

  • deviceIdstringDeviceId

    ID 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

  • deviceIdstringDeviceId

    ID 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

  • deviceIdstringDeviceId

    ID of the device.

  • namestringoptional

    New 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

  • deviceIdstringDeviceId

    ID of the device.

  • validForSecsintegeroptional

    Token validity duration in seconds. Defaults to 600 seconds (10 minutes).

    • Token validity must be between 1 second and 1 year.
  • claimsanyJsonValueoptional

    Additional user-defined claims.

    Nexigon Hub rejects claims larger than the instance's limit, 4 KiB by default.

Response IssueDeviceTokenOutput

  • jwtstringJwt

    Issued 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

  • jwtstringJwt

    JWT to validate.

Response ValidateDeviceTokenOutput

One of the following, identified by result:

  • result: "Invalid"

    The JWT is invalid.

  • result: "Valid"

    The JWT is valid.

    • deviceIdstringDeviceId

      ID of the device.

    • claimsanyJsonValue

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

  • deviceIdstringDeviceId

    ID of the device.

  • fingerprintstringCertificateFingerprint

    Fingerprint of the certificate.

  • statusstringDeviceCertificateStatusoptional

    Initial 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

  • certificateIdstringDeviceCertificateId

    ID 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

  • certificateIdstringDeviceCertificateId

    ID 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

  • certificateIdstringDeviceCertificateId

    ID of the certificate.

  • statusstringDeviceCertificateStatus

    New 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

  • deviceIdstringDeviceId

    ID of the device.

  • nodeIdstringClusterNodeId

    ID of the cluster node.

  • connectionIdstringDeviceConnectionId

    Pre-generated ID of the connection.

Response RegisterDeviceConnectionOutput

  • connectionIdstringDeviceConnectionId

    ID 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

  • connectionIdstringDeviceConnectionId

    ID of the connection.

  • endReasonstringConnectionEndReason

    Reason 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

  • deviceIdstringDeviceId

    ID of the device.

  • limitintegeroptional

    Limit results (default 100).

    • Limit must be between 1 and 1000.
  • activeOnlybooleanoptional

    Include only active connections.

Response QueryDeviceConnectionsOutput

  • connectionsarray<object>DeviceConnectionLog

    List of connections.

    6 fields
    • connectionIdstringDeviceConnectionId

      ID of the connection.

    • nodeIdstringClusterNodeId

      ID of the cluster node.

    • connectedAtstring (date-time)Timestamp

      Timestamp when the connection was established.

    • endedAtstring (date-time)Timestampoptional

      Timestamp when the connection ended (null if still connected).

    • endReasonstringConnectionEndReasonoptional

      Reason 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.

    • durationSecsinteger

      Duration 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

  • deviceIdstringDeviceId

    ID of the device.

  • validForSecsintegeroptional

    Token validity duration in seconds.

    • Token validity must be between 1 second and 1 year.
  • hostnamestringoptional

    Hostname 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.
  • portintegeroptional

    Device port to proxy to.

    Defaults to 80.

    • Port must be between 1 and 65535.
  • redirectstringoptional

    Redirect URL in case the token is expired or invalid.

    • Redirect URL must be between 1 and 2048 characters.

Response IssueDeviceHttpProxyTokenOutput

  • jwtstringJwt

    JWT proxy token.

  • urlstring

    Proxy 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

  • jwtstringJwt

    JWT to validate.

Response ValidateDeviceHttpProxyTokenOutput

One of the following, identified by result:

  • result: "Invalid"

    The JWT is invalid.

    • redirectstringoptional

      URL to redirect to.

  • result: "Valid"

    The JWT is valid.

    • deviceIdstringDeviceId

      ID of the device.

    • issuerobjectActoroptional

      Actor 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.

        • deviceIdstringDeviceId

          ID of the device.

        • tokenIdstringDeploymentTokenId

          ID of the deployment token used for authentication.

      • actor: "User"

        A user typically authenticated via a user session.

        • userIdstringUserId

          ID of the user.

      • actor: "UserToken"

        A user authenticated via a specific token.

        • userIdstringUserId

          ID of the user.

        • tokenIdstringUserTokenId

          ID of the user token used for authentication.

      • actor: "ClusterNode"

        A cluster node.

        • nodeIdstringClusterNodeId

          ID of the cluster node.

      • actor: "OrganizationApiToken"

        An organization API token.

        • organizationIdstringOrganizationId

          ID of the organization.

        • tokenIdstringOrganizationApiTokenId

          ID of the API token.

    • hostnamestringoptional

      Hostname to accept requests for.

    • portintegeroptional

      Device 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

  • deviceIdstringDeviceId

    ID of the device.

  • eventsarray<object>DeviceEvent

    Events to publish.

    7 fields
    • eventIdstringDeviceEventId

      ID of the event.

    • categorystringoptional

      Category identifying the type of the event. Keep the set of categories small.

      • Event category must be between 1 and 128 characters.
    • severitystringDeviceEventSeverity

      Severity of the event.

      • "Trace"

        Tracing event.

      • "Debug"

        Debugging event.

      • "Info"

        Informational event.

      • "Warning"

        Warning event.

      • "Error"

        Error event.

      • "Critical"

        Critical event.

    • bodyanyJsonValue

      Event body.

    • attributesmap<string, any>JsonValue

      Event attributes.

    • emittedAtstring (date-time)Timestamp

      Timestamp when the event was emitted.

    • receivedAtstring (date-time)Timestampoptional

      Timestamp 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

  • pageobjectPageRequestoptional

    Opt into cursor pagination. Without this field, the existing limit applies.

    2 fields
    • limitintegeroptional

      Maximum 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.
    • cursorstringPageCursoroptional

      Continue the same endpoint, scope, filters, and ordering.

  • deviceIdstringDeviceId

    ID of the device.

  • limitintegeroptional

    Limit the number of events to return.

    Default to 100.

    • Limit must be between 1 and 1000.

Response QueryDeviceEventsOutput

  • pageobjectPageInfooptional

    Present when cursor pagination was requested.

    1 field
    • nextCursorstringPageCursoroptional

      Cursor for the next page; absent when no more matching rows were visible.

  • eventsarray<object>DeviceEvent

    List of events.

    7 fields
    • eventIdstringDeviceEventId

      ID of the event.

    • categorystringoptional

      Category identifying the type of the event. Keep the set of categories small.

      • Event category must be between 1 and 128 characters.
    • severitystringDeviceEventSeverity

      Severity of the event.

      • "Trace"

        Tracing event.

      • "Debug"

        Debugging event.

      • "Info"

        Informational event.

      • "Warning"

        Warning event.

      • "Error"

        Error event.

      • "Critical"

        Critical event.

    • bodyanyJsonValue

      Event body.

    • attributesmap<string, any>JsonValue

      Event attributes.

    • emittedAtstring (date-time)Timestamp

      Timestamp when the event was emitted.

    • receivedAtstring (date-time)Timestampoptional

      Timestamp 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

  • deviceIdstringDeviceId

    ID of the device.

  • namestring

    Name 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.
  • valueanyJsonValue

    Value of the property.

    Nexigon Hub rejects values larger than the instance's limit, 64 KiB by default.

  • protectedbooleanoptional

    Indicates whether the property should be protected.

  • expectedVersioninteger (64-bit)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.

Response SetDevicePropertyOutput

One of the following, identified by result:

  • result: "Set"

    The property was set successfully.

    • versioninteger (64-bit)optional

      The 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

  • deviceIdstringDeviceId

    ID of the device.

  • namestring

    Name 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.

    • namestring

      Name of the property.

    • valueanyJsonValue

      Value of the property.

    • protectedboolean

      Indicates 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)Timestamp

      Last 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

  • deviceIdstringDeviceId

    ID of the device.

  • namestring

    Name 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

  • deviceIdstringDeviceId

    ID of the device.

Response QueryDevicePropertiesOutput

  • propertiesmap<string, object>DeviceProperty

    List of properties.

    5 fields
    • namestring

      Name of the property.

    • valueanyJsonValue

      Value of the property.

    • protectedboolean

      Indicates 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)Timestamp

      Last 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

  • deviceIdstringDeviceId

    ID of the device.

Response QueryDevicePropertySourcesOutput

  • propertiesmap<string, object>DevicePropertySources

    Sources 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>DevicePropertyProfileValue

      Values set by the device's profiles, in the order they apply.

      4 fields
      • profileIdstringDeviceProfileId
      • revisioninteger

        Revision of the profile that sets the value.

      • valueanyJsonValue
      • protectedboolean
    • deviceobjectDevicePropertyDeviceValueoptional

      Value set on the device itself.

      2 fields
      • valueanyJsonValue
      • protectedboolean

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

  • pageobjectPageRequestoptional

    Opt into cursor pagination. Without this field, the existing limit applies.

    2 fields
    • limitintegeroptional

      Maximum 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.
    • cursorstringPageCursoroptional

      Continue the same endpoint, scope, filters, and ordering.

  • deviceIdstringDeviceId

    ID of the device.

Response QueryDeviceAuditLogOutput

  • pageobjectPageInfooptional

    Present when cursor pagination was requested.

    1 field
    • nextCursorstringPageCursoroptional

      Cursor for the next page; absent when no more matching rows were visible.

  • eventsarray<object>AuditLogEvent

    List of audit log events.

    7 fields
    • eventIdstringAuditLogEventId

      ID of the audit log event.

    • actorobjectActor

      Actor 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.

        • deviceIdstringDeviceId

          ID of the device.

        • tokenIdstringDeploymentTokenId

          ID of the deployment token used for authentication.

      • actor: "User"

        A user typically authenticated via a user session.

        • userIdstringUserId

          ID of the user.

      • actor: "UserToken"

        A user authenticated via a specific token.

        • userIdstringUserId

          ID of the user.

        • tokenIdstringUserTokenId

          ID of the user token used for authentication.

      • actor: "ClusterNode"

        A cluster node.

        • nodeIdstringClusterNodeId

          ID of the cluster node.

      • actor: "OrganizationApiToken"

        An organization API token.

        • organizationIdstringOrganizationId

          ID of the organization.

        • tokenIdstringOrganizationApiTokenId

          ID of the API token.

    • eventstring

      Type of the event that was recorded.

    • dataanyJsonValue

      Additional audit data associated with the event.

    • createdAtstring (date-time)Timestamp

      Timestamp indicating when the audit log event was recorded.

    • actionobjectAuditLogEventActionoptional

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

      1 field
      • actionIdstringAuditLogActionId

        ID of the action.

    • jobobjectAuditLogEventJoboptional

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

      1 field
      • jobIdstringJobId

        ID of the job.

  • referencesobjectAuditLogReferencesoptional

    Names of the actors of the returned events.

    Absent in responses of Nexigon Hub 2026.3 and earlier.

    3 fields
    • usersarray<object>AuditLogUserReference

      Users acting directly or through a user token.

      3 fields
      • userIdstringUserId

        ID of the user.

      • displayNamestringoptional

        Name of the user.

      • emailstring

        Email of the user.

    • devicesarray<object>AuditLogDeviceReference

      Devices.

      2 fields
      • deviceIdstringDeviceId

        ID of the device.

      • namestring

        Name of the device.

    • organizationApiTokensarray<object>AuditLogOrganizationApiTokenReference

      Organization API tokens.

      2 fields
      • tokenIdstringOrganizationApiTokenId

        ID of the API token.

      • namestring

        Name 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

  • deviceIdstringDeviceId

    ID of the device.

Response QueryDeviceCommandsOutput

  • manifestobjectDeviceCommandManifest

    Command manifest.

    1 field
    • commandsarray<object>DeviceCommandDescriptor

      Available commands.

      5 fields
      • namestring

        Command name.

      • descriptionstringoptional

        Description of what the command does.

      • categorystringoptional

        Category for grouping in the UI.

      • inputanyJsonValueoptional

        JSON Schema for the command input.

      • outputanyJsonValueoptional

        JSON 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

  • projectIdstringProjectId
  • deviceIdsarray<string>DeviceId
    • Select at least one device.
  • addarray<string>DeviceGroupId
  • removearray<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

  • deviceIdstringDeviceId
  • profilesarray<object>DeviceProfileAssignment

    Profiles of the device and their modes, in the order they apply. A profile may appear only once.

    2 fields
    • profileIdstringDeviceProfileId
    • modeobjectDeviceProfileModeoptional

      Defaults 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

  • projectIdstringProjectId
  • deviceIdsarray<string>DeviceId
    • Select at least one device.
  • addarray<object>DeviceProfileAssignment

    Profiles to add with their modes, in the order they apply after a device's other profiles.

    2 fields
    • profileIdstringDeviceProfileId
    • modeobjectDeviceProfileModeoptional

      Defaults 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>DeviceProfileId

    Profiles 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

  • deviceIdstringDeviceId

    ID of the device.

Response QueryDeviceOperationsOutput

  • operationsarray<object>DeviceOperationSummary

    Device operations.

    15 fields
    • deviceOperationIdstringDeviceOperationId

      ID of the operation.

    • projectIdstringProjectId

      Project the device belongs to.

    • deviceIdstringDeviceId

      Device the operation is bound to.

    • createdByobjectActoroptional

      Actor 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.

        • deviceIdstringDeviceId

          ID of the device.

        • tokenIdstringDeploymentTokenId

          ID of the deployment token used for authentication.

      • actor: "User"

        A user typically authenticated via a user session.

        • userIdstringUserId

          ID of the user.

      • actor: "UserToken"

        A user authenticated via a specific token.

        • userIdstringUserId

          ID of the user.

        • tokenIdstringUserTokenId

          ID of the user token used for authentication.

      • actor: "ClusterNode"

        A cluster node.

        • nodeIdstringClusterNodeId

          ID of the cluster node.

      • actor: "OrganizationApiToken"

        An organization API token.

        • organizationIdstringOrganizationId

          ID of the organization.

        • tokenIdstringOrganizationApiTokenId

          ID of the API token.

    • fleetOperationIdstringFleetOperationIdoptional

      Fleet operation that materialized this operation, if any.

      Absent for operations created directly against the device.

    • namestring

      Operation name.

      A standalone device operation owns this name. A fleet-owned device operation inherits it from its fleet operation.

    • descriptionstringoptional

      Optional description.

    • statusstringDeviceOperationStatus

      Lifecycle 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.

    • stepIndexinteger

      Current step index.

    • stepCountinteger

      Number of configured steps.

    • lastErrorstringoptional

      Last step or operation error.

    • createdAtstring (date-time)Timestamp

      Creation time.

    • startedAtstring (date-time)Timestampoptional

      Start time.

    • completedAtstring (date-time)Timestampoptional

      Completion time.

    • updatedAtstring (date-time)Timestamp

      Last 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

  • deviceOperationIdstringDeviceOperationId

    ID 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.

    • summaryobjectDeviceOperationSummary

      Summary.

      15 fields
      • deviceOperationIdstringDeviceOperationId

        ID of the operation.

      • projectIdstringProjectId

        Project the device belongs to.

      • deviceIdstringDeviceId

        Device the operation is bound to.

      • createdByobjectActoroptional

        Actor 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.

          • deviceIdstringDeviceId

            ID of the device.

          • tokenIdstringDeploymentTokenId

            ID of the deployment token used for authentication.

        • actor: "User"

          A user typically authenticated via a user session.

          • userIdstringUserId

            ID of the user.

        • actor: "UserToken"

          A user authenticated via a specific token.

          • userIdstringUserId

            ID of the user.

          • tokenIdstringUserTokenId

            ID of the user token used for authentication.

        • actor: "ClusterNode"

          A cluster node.

          • nodeIdstringClusterNodeId

            ID of the cluster node.

        • actor: "OrganizationApiToken"

          An organization API token.

          • organizationIdstringOrganizationId

            ID of the organization.

          • tokenIdstringOrganizationApiTokenId

            ID of the API token.

      • fleetOperationIdstringFleetOperationIdoptional

        Fleet operation that materialized this operation, if any.

        Absent for operations created directly against the device.

      • namestring

        Operation name.

        A standalone device operation owns this name. A fleet-owned device operation inherits it from its fleet operation.

      • descriptionstringoptional

        Optional description.

      • statusstringDeviceOperationStatus

        Lifecycle 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.

      • stepIndexinteger

        Current step index.

      • stepCountinteger

        Number of configured steps.

      • lastErrorstringoptional

        Last step or operation error.

      • createdAtstring (date-time)Timestamp

        Creation time.

      • startedAtstring (date-time)Timestampoptional

        Start time.

      • completedAtstring (date-time)Timestampoptional

        Completion time.

      • updatedAtstring (date-time)Timestamp

        Last update time.

    • stepsarray<object>DeviceOperationStep

      Ordered steps.

      5 variants

      One of the following, identified by kind:

      • kind: "SetDeviceProperty"

        Set the device's own value of a property.

        • whenstringoptional

          Expression 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.
        • namestring

          Property 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.
        • valueanyJsonValue

          Value to set.

          Nexigon Hub rejects values larger than the instance's limit, 64 KiB by default.

        • protectedbooleanoptional

          Whether the property is protected. Defaults to false.

      • kind: "PatchDeviceProperty"

        Apply a JSON merge patch to the device's own value of a property.

        • whenstringoptional

          Expression 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.
        • namestring

          Property 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.
        • patchanyJsonValue

          Patch 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.

        • protectedbooleanoptional

          Whether 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.

        • whenstringoptional

          Expression 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.
        • namestring

          Property 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.

        • whenstringoptional

          Expression 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.
        • commandstring

          Command name from the device command manifest.

          • Command name must be between 1 and 256 characters.
        • inputanyJsonValue

          Command input.

          Nexigon Hub rejects inputs larger than the instance's limit, 64 KiB by default.

        • timeoutSecsintegeroptional

          Time 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.

        • whenstringoptional

          Expression 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.
        • expressionstring

          Expression that finishes the wait once it is true.

          • Expressions must be between 1 and 4096 characters.
        • failureExpressionstringoptional

          Expression that fails the step once it is true. It takes precedence over expression.

          • Expressions must be at most 4096 characters.
        • timeoutSecsintegeroptional

          Time 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>DeviceOperationStepState

      State 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 steps by step_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
      • stepIndexinteger

        Index into DeviceOperationDetails.steps of the step this state is for.

      • statusstringDeviceOperationStepStatus

        Step 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.

      • outputanyJsonValueoptional

        Output that the device reported for a command.

      • omittedOutputBytesinteger (64-bit)optional

        Size 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.

      • errorstringoptional

        Error message when the step failed or timed out, or the latest error of a waiting step's expressions.

      • startedAtstring (date-time)Timestampoptional

        When the step started running.

      • completedAtstring (date-time)Timestampoptional

        When 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

  • deviceIdstringDeviceId

    Device the operation is bound to.

  • namestring

    Operation name.

    • Device operation name must be between 1 and 128 characters.
  • descriptionstringoptional

    Optional description.

    • Device operation description must be at most 4096 characters.
  • stepsarray<object>DeviceOperationStep

    Ordered steps.

    5 variants

    One of the following, identified by kind:

    • kind: "SetDeviceProperty"

      Set the device's own value of a property.

      • whenstringoptional

        Expression 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.
      • namestring

        Property 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.
      • valueanyJsonValue

        Value to set.

        Nexigon Hub rejects values larger than the instance's limit, 64 KiB by default.

      • protectedbooleanoptional

        Whether the property is protected. Defaults to false.

    • kind: "PatchDeviceProperty"

      Apply a JSON merge patch to the device's own value of a property.

      • whenstringoptional

        Expression 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.
      • namestring

        Property 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.
      • patchanyJsonValue

        Patch 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.

      • protectedbooleanoptional

        Whether 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.

      • whenstringoptional

        Expression 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.
      • namestring

        Property 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.

      • whenstringoptional

        Expression 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.
      • commandstring

        Command name from the device command manifest.

        • Command name must be between 1 and 256 characters.
      • inputanyJsonValue

        Command input.

        Nexigon Hub rejects inputs larger than the instance's limit, 64 KiB by default.

      • timeoutSecsintegeroptional

        Time 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.

      • whenstringoptional

        Expression 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.
      • expressionstring

        Expression that finishes the wait once it is true.

        • Expressions must be between 1 and 4096 characters.
      • failureExpressionstringoptional

        Expression that fails the step once it is true. It takes precedence over expression.

        • Expressions must be at most 4096 characters.
      • timeoutSecsintegeroptional

        Time 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

  • deviceOperationIdstringDeviceOperationId

    ID 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

  • deviceOperationIdstringDeviceOperationId

    ID 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

  • deviceOperationIdstringDeviceOperationId

    ID 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

  • deviceIdstringDeviceId

    ID of the device claiming work.

  • limitintegeroptional

    Maximum number of work items to claim. Defaults to 1.

    • Claim limit must be between 1 and 20.
  • kindsarray<string>DeviceOperationWorkKindoptional

    Work kinds to return. Defaults to all device-executable work.

    • "DeviceCommand"

      Command work, which Nexigon Agent runs with its device commands.

Response ClaimDeviceOperationWorkOutput

  • workarray<object>DeviceOperationWorkItem

    Work items leased to the device.

    5 fields
    • deviceOperationIdstringDeviceOperationId

      ID of the device operation the work belongs to.

    • claimIdstringDeviceOperationWorkClaimId

      Claim 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.

    • operationNamestring

      Name of the standalone or fleet operation that defined this work.

    • stepIndexinteger

      Zero-based index of the step within the device operation. Pass it to devices_ReportOperationStep with the claim.

    • stepobjectDeviceOperationWorkStep

      Step to run.

      1 variant

      One of the following, identified by kind:

      • kind: "DeviceCommand"

        Run an on-device command and report its result.

        • commandstring

          Command name from the device command manifest.

        • inputanyJsonValue

          Command input.

        • timeoutSecsintegeroptional

          Execution 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

  • deviceIdstringDeviceId

    ID of the reporting device.

  • deviceOperationIdstringDeviceOperationId

    ID of the operation.

  • stepIndexinteger

    Step index being reported.

  • claimIdstringDeviceOperationWorkClaimId

    Claim returned by the poll that delivered this work item.

  • reportobjectDeviceOperationStepReport

    Reported step outcome.

    3 fields
    • statusstringDeviceOperationStepReportStatus

      Result status.

      • "Succeeded"

        Step succeeded.

      • "Failed"

        Step failed.

    • outputanyJsonValueoptional

      Command output.

      Nexigon Hub stores outputs up to the instance's limit, 64 KiB by default, and only the size of larger outputs.

    • errorstringoptional

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