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)

  • devicesrequired

    List of devices.

    array<QueryDevicesItem>

    Items

    QueryDevicesItem

    Fields (JSON object)

    • deviceId(from device_id)required

      ID of the device.

      DeviceIdstring
    • projectId(from project_id)required

      Project ID of the device.

      ProjectIdstring
    • isConnected(from is_connected)required

      Indicates whether the device is currently connected.

      boolean
    • lastConnectedAt(from last_connected_at)optional

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

      Timestampstring
    • currentConnectionDurationSecs(from current_connection_duration_secs)optional

      Duration of the current connection in seconds (null if not connected).

      integer

devices_GetDetails

POST/api/v1/actions/invoke/devices_GetDetails

Get information about a device.

Request GetDeviceDetailsAction

Fields (JSON object)

  • deviceId(from device_id)required

    ID of the device.

    DeviceIdstring

Response GetDeviceDetailsOutput

Fields (JSON object)

  • deviceId(from device_id)required

    ID of the device.

    DeviceIdstring
  • projectId(from project_id)required

    Project ID of the device.

    ProjectIdstring
  • fingerprintId(from fingerprint_id)required

    Fingerprint ID the device.

    DeviceFingerprintIdstring
  • nameoptional

    Name of the device.

    string
  • isConnected(from is_connected)required

    Indicates whether the device is online.

    boolean
  • certificatesrequired

    Certificates of the device.

    array<DeviceCertificate>

    Items

    DeviceCertificate

    Fields (JSON object)

    • certificateId(from certificate_id)required

      ID of the certificate.

      DeviceCertificateIdstring
    • statusrequired

      Status of the certificate.

      DeviceCertificateStatus

      Casesexternally

      • Pending

        The certificate is pending.

        Value: "Pending"

      • Active

        The certificate is active.

        Value: "Active"

      • Rejected

        The certificate has been rejected.

        Value: "Rejected"

      • Revoked

        The certificate has been revoked.

        Value: "Revoked"

      • Conflict

        The certificate fingerprint was seen on multiple devices.

        Value: "Conflict"

    • fingerprintrequired

      Fingerprint of the certificate.

      CertificateFingerprintstring
    • firstSeen(from first_seen)required

      Timestamp when the certificate was first seen.

      Timestampstring
  • connectionsrequired

    Connections of the device.

    array<DeviceConnection>

    Items

    DeviceConnection

    Fields (JSON object)

    • connectionId(from connection_id)required

      ID of the connection.

      DeviceConnectionIdstring
    • nodeId(from node_id)required

      ID of the cluster node.

      ClusterNodeIdstring
    • connectedAt(from connected_at)required

      Timestamp when the connection was established.

      Timestampstring
    • connectedForSecs(from connected_for_secs)required

      Duration of the connection in seconds.

      integer

devices_Create

POST/api/v1/actions/invoke/devices_Create

Create a new device.

Request CreateDeviceAction

Fields (JSON object)

  • projectId(from project_id)required

    ID of the project.

    ProjectIdstring
  • fingerprintrequired

    Fingerprint of the device.

    DeviceFingerprintstring

Response CreateDeviceOutput

Fields (JSON object)

  • deviceId(from device_id)required

    ID of the device.

    DeviceIdstring

devices_Delete

POST/api/v1/actions/invoke/devices_Delete

Delete a device.

Request DeleteDeviceAction

Fields (JSON object)

  • deviceId(from device_id)required

    ID of the device.

    DeviceIdstring

Response Empty

No fields.

devices_SetName

POST/api/v1/actions/invoke/devices_SetName

Set the name of a device.

Request SetDeviceNameAction

Fields (JSON object)

  • deviceId(from device_id)required

    ID of the device.

    DeviceIdstring
  • nameoptional

    New name of the device.

    string

Response Empty

No fields.

devices_IssueDeviceToken

POST/api/v1/actions/invoke/devices_IssueDeviceToken

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

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

Request IssueDeviceTokenAction

Fields (JSON object)

  • deviceId(from device_id)required

    ID of the device.

    DeviceIdstring
  • validForSecs(from valid_for_secs)optional

    Token validity duration in seconds.

    integer
  • claimsoptional

    Additional user-defined claims.

    JsonValueany

Response IssueDeviceTokenOutput

Fields (JSON object)

  • jwtrequired

    Issued JWT.

    Jwt

    Wraps

    string

devices_ValidateDeviceToken

POST/api/v1/actions/invoke/devices_ValidateDeviceToken

Validate a device JWT.

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

Request ValidateDeviceTokenAction

Fields (JSON object)

  • jwtrequired

    JWT to validate.

    Jwt

    Wraps

    string

Response ValidateDeviceTokenOutput

Casesinternally — tag field result

  • Invalid

    The JWT is invalid.

    { "result": "Invalid" }

  • Valid

    The JWT is valid.

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

    ValidateDeviceTokenSuccess

    Fields (JSON object)

    • deviceId(from device_id)required

      ID of the device.

      DeviceIdstring
    • claimsrequired

      User-defined claims.

      JsonValueany

devices_AddCertificate

POST/api/v1/actions/invoke/devices_AddCertificate

Add a device certificate.

Request AddDeviceCertificateAction

Fields (JSON object)

  • deviceId(from device_id)required

    ID of the device.

    DeviceIdstring
  • fingerprintrequired

    Fingerprint of the certificate.

    CertificateFingerprintstring
  • statusoptional

    Initial status of the certificate.

    Defaults to Pending.

    DeviceCertificateStatus

    Casesexternally

    • Pending

      The certificate is pending.

      Value: "Pending"

    • Active

      The certificate is active.

      Value: "Active"

    • Rejected

      The certificate has been rejected.

      Value: "Rejected"

    • Revoked

      The certificate has been revoked.

      Value: "Revoked"

    • Conflict

      The certificate fingerprint was seen on multiple devices.

      Value: "Conflict"

Response AddDeviceCertificateOutput

Fields (JSON object)

  • certificateId(from certificate_id)required

    ID of the certificate.

    DeviceCertificateIdstring

devices_DeleteCertificate

POST/api/v1/actions/invoke/devices_DeleteCertificate

Delete a device certificate.

Request DeleteDeviceCertificateAction

Fields (JSON object)

  • certificateId(from certificate_id)required

    ID of the certificate.

    DeviceCertificateIdstring

Response Empty

No fields.

devices_SetCertificateStatus

POST/api/v1/actions/invoke/devices_SetCertificateStatus

Set the status of a device certificate.

Request SetDeviceCertificateStatusAction

Fields (JSON object)

  • certificateId(from certificate_id)required

    ID of the certificate.

    DeviceCertificateIdstring
  • statusrequired

    New status of the certificate.

    DeviceCertificateStatus

    Casesexternally

    • Pending

      The certificate is pending.

      Value: "Pending"

    • Active

      The certificate is active.

      Value: "Active"

    • Rejected

      The certificate has been rejected.

      Value: "Rejected"

    • Revoked

      The certificate has been revoked.

      Value: "Revoked"

    • Conflict

      The certificate fingerprint was seen on multiple devices.

      Value: "Conflict"

Response Empty

No fields.

devices_RegisterConnection

POST/api/v1/actions/invoke/devices_RegisterConnection

Register a connection of a device to a cluster node.

Request RegisterDeviceConnectionAction

Fields (JSON object)

  • deviceId(from device_id)required

    ID of the device.

    DeviceIdstring
  • nodeId(from node_id)required

    ID of the cluster node.

    ClusterNodeIdstring
  • connectionId(from connection_id)required

    Pre-generated ID of the connection.

    DeviceConnectionIdstring

Response RegisterDeviceConnectionOutput

Fields (JSON object)

  • connectionId(from connection_id)required

    ID of the connection.

    DeviceConnectionIdstring

devices_UnregisterConnection

POST/api/v1/actions/invoke/devices_UnregisterConnection

Unregister a connection of a device to a cluster node.

Request UnregisterDeviceConnectionAction

Fields (JSON object)

  • connectionId(from connection_id)required

    ID of the connection.

    DeviceConnectionIdstring
  • endReason(from end_reason)required

    Reason for ending the connection.

    ConnectionEndReason

    Casesexternally

    • Unknown

      Unknown reason (fallback).

      Value: "Unknown"

    • Disconnected

      Device disconnected normally.

      Value: "Disconnected"

    • NodeCrashed

      Connection ended due to cluster node crash or heartbeat timeout.

      Value: "NodeCrashed"

    • ServerShutdown

      Connection ended due to graceful server shutdown.

      Value: "ServerShutdown"

Response Empty

No fields.

devices_QueryConnections

POST/api/v1/actions/invoke/devices_QueryConnections

Query the connection history of a device.

Request QueryDeviceConnectionsAction

Fields (JSON object)

  • deviceId(from device_id)required

    ID of the device.

    DeviceIdstring
  • limitoptional

    Limit results (default 100).

    integer
  • activeOnly(from active_only)optional

    Include only active connections.

    boolean

Response QueryDeviceConnectionsOutput

Fields (JSON object)

  • connectionsrequired

    List of connections.

    array<DeviceConnectionLog>

    Items

    DeviceConnectionLog

    Fields (JSON object)

    • connectionId(from connection_id)required

      ID of the connection.

      DeviceConnectionIdstring
    • nodeId(from node_id)required

      ID of the cluster node.

      ClusterNodeIdstring
    • connectedAt(from connected_at)required

      Timestamp when the connection was established.

      Timestampstring
    • endedAt(from ended_at)optional

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

      Timestampstring
    • endReason(from end_reason)optional

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

      ConnectionEndReason

      Casesexternally

      • Unknown

        Unknown reason (fallback).

        Value: "Unknown"

      • Disconnected

        Device disconnected normally.

        Value: "Disconnected"

      • NodeCrashed

        Connection ended due to cluster node crash or heartbeat timeout.

        Value: "NodeCrashed"

      • ServerShutdown

        Connection ended due to graceful server shutdown.

        Value: "ServerShutdown"

    • durationSecs(from duration_secs)required

      Duration of the connection in seconds.

      integer

devices_IssueHttpProxyToken

POST/api/v1/actions/invoke/devices_IssueHttpProxyToken

Issue a HTTP proxy JWT.

Request IssueDeviceHttpProxyTokenAction

Fields (JSON object)

  • deviceId(from device_id)required

    ID of the device.

    DeviceIdstring
  • validForSecs(from valid_for_secs)optional

    Token validity duration in seconds.

    integer
  • hostnameoptional

    Hostname to accept requests for.

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

    string
  • portoptional

    Device port to proxy to.

    Defaults to 80.

    integer
  • redirectoptional

    Redirect URL in case the token is expired or invalid.

    string

Response IssueDeviceHttpProxyTokenOutput

Fields (JSON object)

  • jwtrequired

    JWT proxy token.

    Jwt

    Wraps

    string
  • urlrequired

    Proxy URL.

    string

devices_ValidateHttpProxyToken

POST/api/v1/actions/invoke/devices_ValidateHttpProxyToken

Validate a HTTP proxy JWT.

Request ValidateDeviceHttpProxyTokenAction

Fields (JSON object)

  • jwtrequired

    JWT to validate.

    Jwt

    Wraps

    string

Response ValidateDeviceHttpProxyTokenOutput

Casesinternally — tag field result

  • Invalid

    The JWT is invalid.

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

    ValidateDeviceHttpProxyTokenInvalid

    Fields (JSON object)

    • redirectoptional

      URL to redirect to.

      string
  • Valid

    The JWT is valid.

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

    ValidateDeviceHttpProxyTokenSuccess

    Fields (JSON object)

    • deviceId(from device_id)required

      ID of the device.

      DeviceIdstring
    • hostnameoptional

      Hostname to accept requests for.

      string
    • portoptional

      Device port to proxy to.

      integer

devices_PublishEvents

POST/api/v1/actions/invoke/devices_PublishEvents

Publish device events.

Request PublishDeviceEventsAction

Fields (JSON object)

  • deviceId(from device_id)required

    ID of the device.

    DeviceIdstring
  • eventsrequired

    Events to push.

    array<DeviceEvent>

    Items

    DeviceEvent

    Fields (JSON object)

    • eventId(from event_id)required

      ID of the event.

      DeviceEventIdstring
    • categoryoptional

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

      string
    • severityrequired

      Severity of the event.

      DeviceEventSeverity

      Casesexternally

      • Trace

        Tracing event.

        Value: "Trace"

      • Debug

        Debugging event.

        Value: "Debug"

      • Info

        Informational even.

        Value: "Info"

      • Warning

        Warning event.

        Value: "Warning"

      • Error

        Error event.

        Value: "Error"

      • Critical

        Critical event.

        Value: "Critical"

    • bodyrequired

      Event body.

      JsonValueany
    • attributesrequired

      Event attributes.

      object<string, JsonValue>

      Keys

      string

      Values

      JsonValueany
    • emittedAt(from emitted_at)required

      Timestamp when the event was emitted.

      Timestampstring
    • receivedAt(from received_at)optional

      Timestamp when the event was received.

      Timestampstring

Response Empty

No fields.

devices_QueryEvents

POST/api/v1/actions/invoke/devices_QueryEvents

Query device events.

Request QueryDeviceEventsAction

Fields (JSON object)

  • deviceId(from device_id)required

    ID of the device.

    DeviceIdstring
  • limitoptional

    Limit the number of events to return.

    Default to 100.

    integer

Response QueryDeviceEventsOutput

Fields (JSON object)

  • eventsrequired

    List of events.

    array<DeviceEvent>

    Items

    DeviceEvent

    Fields (JSON object)

    • eventId(from event_id)required

      ID of the event.

      DeviceEventIdstring
    • categoryoptional

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

      string
    • severityrequired

      Severity of the event.

      DeviceEventSeverity

      Casesexternally

      • Trace

        Tracing event.

        Value: "Trace"

      • Debug

        Debugging event.

        Value: "Debug"

      • Info

        Informational even.

        Value: "Info"

      • Warning

        Warning event.

        Value: "Warning"

      • Error

        Error event.

        Value: "Error"

      • Critical

        Critical event.

        Value: "Critical"

    • bodyrequired

      Event body.

      JsonValueany
    • attributesrequired

      Event attributes.

      object<string, JsonValue>

      Keys

      string

      Values

      JsonValueany
    • emittedAt(from emitted_at)required

      Timestamp when the event was emitted.

      Timestampstring
    • receivedAt(from received_at)optional

      Timestamp when the event was received.

      Timestampstring

devices_SetProperty

POST/api/v1/actions/invoke/devices_SetProperty

Set a property of a device.

Request SetDevicePropertyAction

Fields (JSON object)

  • deviceId(from device_id)required

    ID of the device.

    DeviceIdstring
  • namerequired

    Name of the property.

    string
  • valuerequired

    Value of the property.

    JsonValueany
  • protectedoptional

    Indicates whether the property should be protected.

    boolean
  • expectedVersion(from expected_version)optional

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

    integer (i64)

Response SetDevicePropertyOutput

Casesinternally — tag field result

  • Set

    The property was set successfully.

    { "result": "Set" }

  • VersionConflict

    The property was not updated because its version did not match the expected version (compare-and-swap conflict).

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

    SetDevicePropertyVersionConflict

    Fields (JSON object)

    • currentVersion(from current_version)required

      The current version of the property.

      integer (i64)
  • Deleted

    The property was not updated because it has been deleted while an expected version was specified.

    { "result": "Deleted" }

devices_GetProperty

POST/api/v1/actions/invoke/devices_GetProperty

Get a property of a device.

Request GetDevicePropertyAction

Fields (JSON object)

  • deviceId(from device_id)required

    ID of the device.

    DeviceIdstring
  • namerequired

    Name of the property.

    string

Response GetDevicePropertyOutput

Casesinternally — tag field result

  • NotFound

    The property was not found.

    { "result": "NotFound" }

  • Found

    The property was found.

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

    DeviceProperty

    Fields (JSON object)

    • namerequired

      Name of the property.

      string
    • valuerequired

      Value of the property.

      JsonValueany
    • protectedrequired

      Indicates whether the property is protected.

      boolean
    • versionrequired

      Incremental version number, incremented on each update.

      integer (i64)
    • lastUpdated(from last_updated)required

      Last time the property was updated.

      Timestampstring

devices_RemoveProperty

POST/api/v1/actions/invoke/devices_RemoveProperty

Remove a property from a device.

Request RemoveDevicePropertyAction

Fields (JSON object)

  • deviceId(from device_id)required

    ID of the device.

    DeviceIdstring
  • namerequired

    Name of the property.

    string

Response RemoveDevicePropertyOutput

Casesinternally — tag field result

  • NotFound

    The property was not found.

    { "result": "NotFound" }

  • Removed

    The property was removed.

    { "result": "Removed" }

devices_QueryProperties

POST/api/v1/actions/invoke/devices_QueryProperties

Query the properties of a device.

Request QueryDevicePropertiesAction

Fields (JSON object)

  • deviceId(from device_id)required

    ID of the device.

    DeviceIdstring

Response QueryDevicePropertiesOutput

Fields (JSON object)

  • propertiesrequired

    List of properties.

    object<string, DeviceProperty>

    Keys

    string

    Values

    DeviceProperty

    Fields (JSON object)

    • namerequired

      Name of the property.

      string
    • valuerequired

      Value of the property.

      JsonValueany
    • protectedrequired

      Indicates whether the property is protected.

      boolean
    • versionrequired

      Incremental version number, incremented on each update.

      integer (i64)
    • lastUpdated(from last_updated)required

      Last time the property was updated.

      Timestampstring

devices_QueryAuditLog

POST/api/v1/actions/invoke/devices_QueryAuditLog

Query the audit log of a device.

Request QueryDeviceAuditLogAction

Fields (JSON object)

  • deviceId(from device_id)required

    ID of the device.

    DeviceIdstring

Response QueryDeviceAuditLogOutput

Fields (JSON object)

  • eventsrequired

    List of audit log events.

    array<AuditLogEvent>

    Items

    AuditLogEvent

    Fields (JSON object)

    • eventId(from event_id)required

      ID of the audit log event.

      AuditLogEventIdstring
    • actorrequired

      Actor causing the event.

      Actor

      Casesinternally — tag field actor

      • Anonymous

        An anonymous, unauthenticated actor.

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

        AnonymousActor

        No fields.

      • System

        The system itself, typically used for internal actions.

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

        SystemActor

        No fields.

      • Device

        A device authenticated via a specific deployment token.

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

        DeviceActor

        Fields (JSON object)

        • deviceId(from device_id)required

          ID of the device.

          DeviceIdstring
        • tokenId(from token_id)required

          ID of the deployment token used for authentication.

          DeploymentTokenIdstring
      • User

        A user typically authenticated via a user session.

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

        UserActor

        Fields (JSON object)

        • userId(from user_id)required

          ID of the user.

          UserIdstring
      • UserToken

        A user authenticated via a specific token.

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

        UserTokenActor

        Fields (JSON object)

        • userId(from user_id)required

          ID of the user.

          UserIdstring
        • tokenId(from token_id)required

          ID of the user token used for authentication.

          UserTokenIdstring
      • ClusterNode

        A cluster node.

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

        ClusterNodeActor

        Fields (JSON object)

        • nodeId(from node_id)required

          ID of the cluster node.

          ClusterNodeIdstring
      • OrganizationApiToken

        An organization API token.

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

        OrganizationApiTokenActor

        Fields (JSON object)

        • organizationId(from organization_id)required

          ID of the organization.

          OrganizationIdstring
        • tokenId(from token_id)required

          ID of the API token.

          OrganizationApiTokenIdstring
    • eventrequired

      Type of the event that was recorded.

      string
    • datarequired

      Additional audit data associated with the event.

      JsonValueany
    • createdAt(from created_at)required

      Timestamp indicating when the audit log event was recorded.

      Timestampstring
    • actionoptional

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

      AuditLogEventAction

      Fields (JSON object)

      • actionId(from action_id)required

        ID of the action.

        AuditLogActionIdstring
    • joboptional

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

      AuditLogEventJob

      Fields (JSON object)

      • jobId(from job_id)required

        ID of the job.

        JobIdstring

devices_QueryCommands

POST/api/v1/actions/invoke/devices_QueryCommands

Query the on-demand commands supported by a device.

Request QueryDeviceCommandsAction

Fields (JSON object)

  • deviceId(from device_id)required

    ID of the device.

    DeviceIdstring

Response QueryDeviceCommandsOutput

Fields (JSON object)

  • manifestrequired

    Command manifest.

    DeviceCommandManifest

    Fields (JSON object)

    • commandsrequired

      Available commands.

      array<DeviceCommandDescriptor>

      Items

      DeviceCommandDescriptor

      Fields (JSON object)

      • namerequired

        Command name.

        string
      • descriptionoptional

        Description of what the command does.

        string
      • categoryoptional

        Category for grouping in the UI.

        string
      • inputoptional

        JSON Schema for the command input.

        JsonValueany
      • outputoptional

        JSON Schema for the command output.

        JsonValueany