Skip to main content
📣 Try Nexigon today — sign up for a free account, no credit card required. 📣
Nexigon Docs
Documentation

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)

  • devices required

    List of devices.

    array<QueryDevicesItem>

    Items

    QueryDevicesItem

    Fields (JSON object)

    • deviceId (from device_id) required

      ID of the device.

      DeviceId string
    • projectId (from project_id) required

      Project ID of the device.

      ProjectId string
    • 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).

      Timestamp string
    • 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.

    DeviceId string

Response GetDeviceDetailsOutput

Fields (JSON object)

  • deviceId (from device_id) required

    ID of the device.

    DeviceId string
  • projectId (from project_id) required

    Project ID of the device.

    ProjectId string
  • fingerprintId (from fingerprint_id) required

    Fingerprint ID the device.

    DeviceFingerprintId string
  • name optional

    Name of the device.

    string
  • isConnected (from is_connected) required

    Indicates whether the device is online.

    boolean
  • certificates required

    Certificates of the device.

    array<DeviceCertificate>

    Items

    DeviceCertificate

    Fields (JSON object)

    • certificateId (from certificate_id) required

      ID of the certificate.

      DeviceCertificateId string
    • status required

      Status of the certificate.

      DeviceCertificateStatus

      Cases externally

      • 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"

    • fingerprint required

      Fingerprint of the certificate.

      CertificateFingerprint string
    • firstSeen (from first_seen) required

      Timestamp when the certificate was first seen.

      Timestamp string
  • connections required

    Connections of the device.

    array<DeviceConnection>

    Items

    DeviceConnection

    Fields (JSON object)

    • connectionId (from connection_id) required

      ID of the connection.

      DeviceConnectionId string
    • nodeId (from node_id) required

      ID of the cluster node.

      ClusterNodeId string
    • connectedAt (from connected_at) required

      Timestamp when the connection was established.

      Timestamp string
    • 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.

    ProjectId string
  • fingerprint required

    Fingerprint of the device.

    DeviceFingerprint string

Response CreateDeviceOutput

Fields (JSON object)

  • deviceId (from device_id) required

    ID of the device.

    DeviceId string

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.

    DeviceId string

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.

    DeviceId string
  • name optional

    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.

    DeviceId string
  • validForSecs (from valid_for_secs) optional

    Token validity duration in seconds.

    integer
  • claims optional

    Additional user-defined claims.

    JsonValue any

Response IssueDeviceTokenOutput

Fields (JSON object)

  • jwt required

    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)

  • jwt required

    JWT to validate.

    Jwt

    Wraps

    string

Response ValidateDeviceTokenOutput

Cases internally — 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.

      DeviceId string
    • claims required

      User-defined claims.

      JsonValue any

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.

    DeviceId string
  • fingerprint required

    Fingerprint of the certificate.

    CertificateFingerprint string
  • status optional

    Initial status of the certificate.

    Defaults to Pending.

    DeviceCertificateStatus

    Cases externally

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

    DeviceCertificateId string

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.

    DeviceCertificateId string

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.

    DeviceCertificateId string
  • status required

    New status of the certificate.

    DeviceCertificateStatus

    Cases externally

    • 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

Register a connection of a device to a cluster node.

Request RegisterDeviceConnectionAction

Fields (JSON object)

  • deviceId (from device_id) required

    ID of the device.

    DeviceId string
  • nodeId (from node_id) required

    ID of the cluster node.

    ClusterNodeId string
  • connectionId (from connection_id) required

    Pre-generated ID of the connection.

    DeviceConnectionId string

Response RegisterDeviceConnectionOutput

Fields (JSON object)

  • connectionId (from connection_id) required

    ID of the connection.

    DeviceConnectionId string

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.

    DeviceConnectionId string
  • endReason (from end_reason) required

    Reason for ending the connection.

    ConnectionEndReason

    Cases externally

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

    DeviceId string
  • limit optional

    Limit results (default 100).

    integer
  • activeOnly (from active_only) optional

    Include only active connections.

    boolean

Response QueryDeviceConnectionsOutput

Fields (JSON object)

  • connections required

    List of connections.

    array<DeviceConnectionLog>

    Items

    DeviceConnectionLog

    Fields (JSON object)

    • connectionId (from connection_id) required

      ID of the connection.

      DeviceConnectionId string
    • nodeId (from node_id) required

      ID of the cluster node.

      ClusterNodeId string
    • connectedAt (from connected_at) required

      Timestamp when the connection was established.

      Timestamp string
    • endedAt (from ended_at) optional

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

      Timestamp string
    • endReason (from end_reason) optional

      Reason why the connection ended (null if still connected).

      ConnectionEndReason

      Cases externally

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

    DeviceId string
  • validForSecs (from valid_for_secs) optional

    Token validity duration in seconds.

    integer
  • hostname optional

    Hostname to accept requests for.

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

    string
  • port optional

    Device port to proxy to.

    Defaults to 80.

    integer
  • redirect optional

    Redirect URL in case the token is expired or invalid.

    string

Response IssueDeviceHttpProxyTokenOutput

Fields (JSON object)

  • jwt required

    JWT proxy token.

    Jwt

    Wraps

    string
  • url required

    Proxy URL.

    string

devices_ValidateHttpProxyToken

POST /api/v1/actions/invoke/devices_ValidateHttpProxyToken

Validate a HTTP proxy JWT.

Request ValidateDeviceHttpProxyTokenAction

Fields (JSON object)

  • jwt required

    JWT to validate.

    Jwt

    Wraps

    string

Response ValidateDeviceHttpProxyTokenOutput

Cases internally — tag field result

  • Invalid

    The JWT is invalid.

    { "result": "Invalid", ...<payload fields> } — or "content" for non-object payloads

    ValidateDeviceHttpProxyTokenInvalid

    Fields (JSON object)

    • redirect optional

      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.

      DeviceId string
    • hostname optional

      Hostname to accept requests for.

      string
    • port optional

      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.

    DeviceId string
  • events required

    Events to push.

    array<DeviceEvent>

    Items

    DeviceEvent

    Fields (JSON object)

    • eventId (from event_id) required

      ID of the event.

      DeviceEventId string
    • category optional

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

      string
    • severity required

      Severity of the event.

      DeviceEventSeverity

      Cases externally

      • 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"

    • body required

      Event body.

      JsonValue any
    • attributes required

      Event attributes.

      object<string, JsonValue>

      Keys

      string

      Values

      JsonValue any
    • emittedAt (from emitted_at) required

      Timestamp when the event was emitted.

      Timestamp string
    • receivedAt (from received_at) optional

      Timestamp when the event was received.

      Timestamp string

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.

    DeviceId string
  • limit optional

    Limit the number of events to return.

    Default to 100.

    integer

Response QueryDeviceEventsOutput

Fields (JSON object)

  • events required

    List of events.

    array<DeviceEvent>

    Items

    DeviceEvent

    Fields (JSON object)

    • eventId (from event_id) required

      ID of the event.

      DeviceEventId string
    • category optional

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

      string
    • severity required

      Severity of the event.

      DeviceEventSeverity

      Cases externally

      • 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"

    • body required

      Event body.

      JsonValue any
    • attributes required

      Event attributes.

      object<string, JsonValue>

      Keys

      string

      Values

      JsonValue any
    • emittedAt (from emitted_at) required

      Timestamp when the event was emitted.

      Timestamp string
    • receivedAt (from received_at) optional

      Timestamp when the event was received.

      Timestamp string

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.

    DeviceId string
  • name required

    Name of the property.

    string
  • value required

    Value of the property.

    JsonValue any
  • protected optional

    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

Cases internally — 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.

    DeviceId string
  • name required

    Name of the property.

    string

Response GetDevicePropertyOutput

Cases internally — 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)

    • name required

      Name of the property.

      string
    • value required

      Value of the property.

      JsonValue any
    • protected required

      Indicates whether the property is protected.

      boolean
    • version required

      Incremental version number, incremented on each update.

      integer (i64)
    • lastUpdated (from last_updated) required

      Last time the property was updated.

      Timestamp string

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.

    DeviceId string
  • name required

    Name of the property.

    string

Response RemoveDevicePropertyOutput

Cases internally — 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.

    DeviceId string

Response QueryDevicePropertiesOutput

Fields (JSON object)

  • properties required

    List of properties.

    object<string, DeviceProperty>

    Keys

    string

    Values

    DeviceProperty

    Fields (JSON object)

    • name required

      Name of the property.

      string
    • value required

      Value of the property.

      JsonValue any
    • protected required

      Indicates whether the property is protected.

      boolean
    • version required

      Incremental version number, incremented on each update.

      integer (i64)
    • lastUpdated (from last_updated) required

      Last time the property was updated.

      Timestamp string

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.

    DeviceId string

Response QueryDeviceAuditLogOutput

Fields (JSON object)

  • events required

    List of audit log events.

    array<AuditLogEvent>

    Items

    AuditLogEvent

    Fields (JSON object)

    • eventId (from event_id) required

      ID of the audit log event.

      AuditLogEventId string
    • actor required

      Actor causing the event.

      Actor

      Cases internally — 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.

          DeviceId string
        • tokenId (from token_id) required

          ID of the deployment token used for authentication.

          DeploymentTokenId string
      • 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.

          UserId string
      • 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.

          UserId string
        • tokenId (from token_id) required

          ID of the user token used for authentication.

          UserTokenId string
      • 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.

          ClusterNodeId string
      • 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.

          OrganizationId string
        • tokenId (from token_id) required

          ID of the API token.

          OrganizationApiTokenId string
    • event required

      Type of the event that was recorded.

      string
    • data required

      Additional audit data associated with the event.

      JsonValue any
    • createdAt (from created_at) required

      Timestamp indicating when the audit log event was recorded.

      Timestamp string
    • action optional

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

      AuditLogEventAction

      Fields (JSON object)

      • actionId (from action_id) required

        ID of the action.

        AuditLogActionId string
    • job optional

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

      AuditLogEventJob

      Fields (JSON object)

      • jobId (from job_id) required

        ID of the job.

        JobId string

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.

    DeviceId string

Response QueryDeviceCommandsOutput

Fields (JSON object)

  • manifest required

    Command manifest.

    DeviceCommandManifest

    Fields (JSON object)

    • commands required

      Available commands.

      array<DeviceCommandDescriptor>

      Items

      DeviceCommandDescriptor

      Fields (JSON object)

      • name required

        Command name.

        string
      • description optional

        Description of what the command does.

        string
      • category optional

        Category for grouping in the UI.

        string
      • input optional

        JSON Schema for the command input.

        JsonValue any
      • output optional

        JSON Schema for the command output.

        JsonValue any