Skip to main content
Documentation

Fleet

Actions in the fleet namespace of the Nexigon Hub API.

Badges mark actions of the Device API and the Admin API, whose compatibility differs from other actions.

fleet_SetProperty

POST/api/v1/actions/invoke/fleet_SetProperty

Set a fleet property manually.

Request SetFleetPropertyAction

  • projectIdstringProjectId

    ID of the project.

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

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>","name":"<name>","value":{}}' \
  $NEXIGON_HUB_URL/api/v1/actions/invoke/fleet_SetProperty
{}

fleet_GetProperty

POST/api/v1/actions/invoke/fleet_GetProperty

Get a fleet property by name.

Request GetFleetPropertyAction

  • projectIdstringProjectId

    ID of the project.

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

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

      Current value.

    • kindobjectFleetPropertyKind

      How this property is managed.

      3 variants

      One of the following, identified by kind:

      • kind: "Manual"

        Set manually via the API.

      • kind: "Computed"
        • Unstable (feature fleet_computed_properties)

        Computed from device properties via a user-defined strategy.

      • kind: "Builtin"
        • Unstable (feature fleet_computed_properties)

        Computed from device properties via a built-in strategy.

    • versioninteger (64-bit)

      Incremental version number, bumped on each update.

    • errorstringoptional

      Error from the last computation attempt, if any.

    • lastUpdatedstring (date-time)Timestamp

      When the value was last updated.

Example

curl --fail-with-body \
  -H "Authorization: Bearer $NEXIGON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"<project-id>","name":"<name>"}' \
  $NEXIGON_HUB_URL/api/v1/actions/invoke/fleet_GetProperty
{
  "result": "Found",
  "name": "<name>",
  "value": {},
  "kind": {
    "kind": "Manual"
  },
  "version": 1,
  "lastUpdated": "2026-01-01T12:00:00Z"
}

fleet_RemoveProperty

POST/api/v1/actions/invoke/fleet_RemoveProperty

Remove a fleet property.

Handles both manual and computed properties. For computed properties, the associated definition is removed as well.

Request RemoveFleetPropertyAction

  • projectIdstringProjectId

    ID of the project.

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

One of the following, identified by result:

  • result: "NotFound"

    The property was not found.

  • result: "Removed"

    The property was removed.

Example

curl --fail-with-body \
  -H "Authorization: Bearer $NEXIGON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"<project-id>","name":"<name>"}' \
  $NEXIGON_HUB_URL/api/v1/actions/invoke/fleet_RemoveProperty
{
  "result": "NotFound"
}

fleet_QueryProperties

POST/api/v1/actions/invoke/fleet_QueryProperties

Query all fleet properties of a project.

Request QueryFleetPropertiesAction

  • projectIdstringProjectId

    ID of the project.

Response QueryFleetPropertiesOutput

  • propertiesmap<string, object>FleetProperty

    Properties keyed by name.

    6 fields
    • namestring

      Name of the property.

    • valueanyJsonValue

      Current value.

    • kindobjectFleetPropertyKind

      How this property is managed.

      3 variants

      One of the following, identified by kind:

      • kind: "Manual"

        Set manually via the API.

      • kind: "Computed"
        • Unstable (feature fleet_computed_properties)

        Computed from device properties via a user-defined strategy.

      • kind: "Builtin"
        • Unstable (feature fleet_computed_properties)

        Computed from device properties via a built-in strategy.

    • versioninteger (64-bit)

      Incremental version number, bumped on each update.

    • errorstringoptional

      Error from the last computation attempt, if any.

    • lastUpdatedstring (date-time)Timestamp

      When the value was last updated.

Example

curl --fail-with-body \
  -H "Authorization: Bearer $NEXIGON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"<project-id>"}' \
  $NEXIGON_HUB_URL/api/v1/actions/invoke/fleet_QueryProperties
{
  "properties": {
    "<key>": {
      "name": "<name>",
      "value": {},
      "kind": {
        "kind": "Manual"
      },
      "version": 1,
      "lastUpdated": "2026-01-01T12:00:00Z"
    }
  }
}

fleet_DefineComputedProperty

POST/api/v1/actions/invoke/fleet_DefineComputedProperty

  • Unstable (feature fleet_computed_properties)

Define a computed fleet property.

Request DefineComputedFleetPropertyAction

  • projectIdstringProjectId

    ID of the project.

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

    Device property names fed into the strategy's map function.

  • strategystring

    Name of the computation strategy.

    • Strategy name must be between 1 and 128 characters.
  • configanyJsonValueoptional

    Strategy-specific configuration.

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

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>",
    "name": "<name>",
    "inputProperties": [
      "<input-properties>"
    ],
    "strategy": "<strategy>"
  }' \
  $NEXIGON_HUB_URL/api/v1/actions/invoke/fleet_DefineComputedProperty
{}

fleet_QueryComputedPropertyDefinitions

POST/api/v1/actions/invoke/fleet_QueryComputedPropertyDefinitions

  • Unstable (feature fleet_computed_properties)

Query computed fleet property definitions for a project.

Request QueryComputedFleetPropertyDefinitionsAction

  • projectIdstringProjectId

    ID of the project.

Response QueryComputedFleetPropertyDefinitionsOutput

  • definitionsarray<object>ComputedFleetPropertyDefinition

    List of definitions.

    5 fields
    • namestring

      Name of the property.

    • inputPropertiesarray<string>

      Device property names fed into the strategy's map function.

    • strategystring

      Name of the computation strategy.

    • configanyJsonValue

      Strategy-specific configuration.

    • createdAtstring (date-time)Timestamp

      When the definition was created.

Example

curl --fail-with-body \
  -H "Authorization: Bearer $NEXIGON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"<project-id>"}' \
  $NEXIGON_HUB_URL/api/v1/actions/invoke/fleet_QueryComputedPropertyDefinitions
{
  "definitions": [
    {
      "name": "<name>",
      "inputProperties": [
        "<input-properties>"
      ],
      "strategy": "<strategy>",
      "config": {},
      "createdAt": "2026-01-01T12:00:00Z"
    }
  ]
}

fleet_QueryOperations

POST/api/v1/actions/invoke/fleet_QueryOperations

List the fleet operations of a project, newest first.

Request QueryFleetOperationsAction

  • projectIdstringProjectId

Response QueryFleetOperationsOutput

  • operationsarray<object>FleetOperationSummary
    14 fields
    • fleetOperationIdstringFleetOperationId
    • projectIdstringProjectId
    • namestring
    • descriptionstringoptional
    • statusstringFleetOperationStatus
      • "Draft"

        The operation has been created but not started.

      • "Running"

        The operation is running.

      • "Halted"

        The operation is halted until it is resumed.

      • "Completed"

        All targets finished, none failed or timed out, and no selection errors remain.

      • "Failed"

        All targets finished, but some failed or timed out, or selection errors remain.

      • "Cancelled"

        The operation was cancelled.

    • enrollmentstringFleetOperationEnrollment
      • "Snapshot"

        Select the targets once, when the operation starts.

      • "Dynamic"

        Select the targets when the operation starts and then periodically, adding devices that start to match, until the operation is closed.

    • deadlineSecsintegeroptional

      Time that each target has to finish after its release, in seconds.

    • progressobjectFleetOperationProgress

      Numbers of the targets by status.

      7 fields
      • totalinteger
      • pendinginteger
      • runninginteger
      • succeededinteger
      • failedinteger
      • timedOutinteger
      • cancelledinteger
    • createdAtstring (date-time)Timestamp
    • startedAtstring (date-time)Timestampoptional
    • haltedAtstring (date-time)Timestampoptional

      Time when the operation was halted, while it is halted or if it was cancelled while halted.

    • closedAtstring (date-time)Timestampoptional

      Time when a dynamic operation stopped selecting further targets.

    • lastEnrollmentAtstring (date-time)Timestampoptional

      Time when the operation last selected targets.

    • completedAtstring (date-time)Timestampoptional

Example

curl --fail-with-body \
  -H "Authorization: Bearer $NEXIGON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"<project-id>"}' \
  $NEXIGON_HUB_URL/api/v1/actions/invoke/fleet_QueryOperations
{
  "operations": [
    {
      "fleetOperationId": "<fleet-operation-id>",
      "projectId": "<project-id>",
      "name": "<name>",
      "status": "Draft",
      "enrollment": "Snapshot",
      "progress": {
        "total": 1,
        "pending": 1,
        "running": 1,
        "succeeded": 1,
        "failed": 1,
        "timedOut": 1,
        "cancelled": 1
      },
      "createdAt": "2026-01-01T12:00:00Z"
    }
  ]
}

fleet_GetOperation

POST/api/v1/actions/invoke/fleet_GetOperation

Get a fleet operation.

Request GetFleetOperationAction

  • fleetOperationIdstringFleetOperationId

Response GetFleetOperationOutput

One of the following, identified by result:

  • result: "NotFound"

    The operation does not exist or the actor cannot access it.

  • result: "Found"

    The operation was found.

    • summaryobjectFleetOperationSummary
      14 fields
      • fleetOperationIdstringFleetOperationId
      • projectIdstringProjectId
      • namestring
      • descriptionstringoptional
      • statusstringFleetOperationStatus
        • "Draft"

          The operation has been created but not started.

        • "Running"

          The operation is running.

        • "Halted"

          The operation is halted until it is resumed.

        • "Completed"

          All targets finished, none failed or timed out, and no selection errors remain.

        • "Failed"

          All targets finished, but some failed or timed out, or selection errors remain.

        • "Cancelled"

          The operation was cancelled.

      • enrollmentstringFleetOperationEnrollment
        • "Snapshot"

          Select the targets once, when the operation starts.

        • "Dynamic"

          Select the targets when the operation starts and then periodically, adding devices that start to match, until the operation is closed.

      • deadlineSecsintegeroptional

        Time that each target has to finish after its release, in seconds.

      • progressobjectFleetOperationProgress

        Numbers of the targets by status.

        7 fields
        • totalinteger
        • pendinginteger
        • runninginteger
        • succeededinteger
        • failedinteger
        • timedOutinteger
        • cancelledinteger
      • createdAtstring (date-time)Timestamp
      • startedAtstring (date-time)Timestampoptional
      • haltedAtstring (date-time)Timestampoptional

        Time when the operation was halted, while it is halted or if it was cancelled while halted.

      • closedAtstring (date-time)Timestampoptional

        Time when a dynamic operation stopped selecting further targets.

      • lastEnrollmentAtstring (date-time)Timestampoptional

        Time when the operation last selected targets.

      • completedAtstring (date-time)Timestampoptional
    • selectorobjectFleetOperationTargetSelector
      3 fields
      • deviceIdsarray<string>DeviceIdoptional

        Devices that may match. Without this field, every device of the project may match.

      • groupsobjectDeviceGroupSelectoroptional

        Group conditions that devices must satisfy.

        3 fields
        • allarray<string>DeviceGroupIdoptional

          Every listed group must be present. Empty or absent imposes no condition.

        • anyarray<string>DeviceGroupIdoptional

          At least one listed group must be present. Empty matches no devices; absence imposes no condition.

        • nonearray<string>DeviceGroupIdoptional

          Every listed group must be absent. Empty or absent imposes no condition.

      • expressionstringoptional

        Expression that devices must satisfy. It can read the variables properties and now.

        A device for which the expression produces an error is not selected. The error is recorded as a selection error.

        • Expressions must be at most 4096 characters.
    • stagesarray<object>FleetOperationStageState

      Stages in the order of their release.

      4 fields
      • definitionobjectRolloutStage
        5 fields
        • namestring
          • Stage name must be between 1 and 128 characters.
        • groupsobjectDeviceGroupSelectoroptional

          Group conditions that the stage's devices satisfy. Without conditions, every device satisfies them.

          3 fields
          • allarray<string>DeviceGroupIdoptional

            Every listed group must be present. Empty or absent imposes no condition.

          • anyarray<string>DeviceGroupIdoptional

            At least one listed group must be present. Empty matches no devices; absence imposes no condition.

          • nonearray<string>DeviceGroupIdoptional

            Every listed group must be absent. Empty or absent imposes no condition.

        • percentagenumberoptional

          Share of the devices that satisfy the conditions, by their position in the rollout, in percent. May have a fraction, such as 0.5. Defaults to 100.

          A device belongs to the first stage whose conditions it satisfies and whose percentage is above its position.

          • Stage percentage must be greater than 0 and at most 100.
        • spreadSecsintegeroptional

          Time over which the stage's devices become active, in seconds. Defaults to 0.

          • Spread must be at most 30 days.
        • guardobjectRolloutGuardoptional

          Conditions for releasing the stage. The first stage is released when the rollout starts and ignores its guard.

          3 fields
          • minCompletedPercentnumberoptional

            Minimal share of the devices in earlier stages that completed, in percent. Defaults to 100.

            • Completed share must be between 0 and 100.
          • maxFailedPercentnumberoptional

            Maximal share of the devices in earlier stages that failed, in percent. Defaults to 0.

            • Failed share must be between 0 and 100.
          • soakSecsintegeroptional

            Minimal time since the previous stage's spread finished, in seconds. Defaults to 0.

            • Soak time must be at most 30 days.
      • releasedAtstring (date-time)Timestampoptional

        Time when the stage was released. Absent until then.

      • targetsobjectFleetOperationProgress

        Numbers of the stage's targets by status.

        7 fields
        • totalinteger
        • pendinginteger
        • runninginteger
        • succeededinteger
        • failedinteger
        • timedOutinteger
        • cancelledinteger
      • guardobjectRolloutGuardStatusoptional

        Progress of the stage's guard. Present for the next stage to release.

        A target counts as completed once it succeeded and as failed once it failed or timed out. Cancelled targets do not count.

        4 fields
        • completedPercentnumber

          Share of the devices in earlier stages that completed, in percent, rounded down to two decimal places.

        • failedPercentnumber

          Share of the devices in earlier stages that failed, in percent, rounded up to two decimal places.

        • remainingSecsinteger

          Seconds until the previous stage's spread and the soak time have passed, on the rollout's clock. Zero once they have.

        • passedboolean

          Whether all conditions of the guard pass.

    • stepsarray<object>DeviceOperationStep

      Steps that each target runs.

      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.

Example

curl --fail-with-body \
  -H "Authorization: Bearer $NEXIGON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"fleetOperationId":"<fleet-operation-id>"}' \
  $NEXIGON_HUB_URL/api/v1/actions/invoke/fleet_GetOperation
{
  "result": "Found",
  "summary": {
    "fleetOperationId": "<fleet-operation-id>",
    "projectId": "<project-id>",
    "name": "<name>",
    "status": "Draft",
    "enrollment": "Snapshot",
    "progress": {
      "total": 1,
      "pending": 1,
      "running": 1,
      "succeeded": 1,
      "failed": 1,
      "timedOut": 1,
      "cancelled": 1
    },
    "createdAt": "2026-01-01T12:00:00Z"
  },
  "selector": {},
  "stages": [
    {
      "definition": {
        "name": "<name>"
      },
      "targets": {
        "total": 1,
        "pending": 1,
        "running": 1,
        "succeeded": 1,
        "failed": 1,
        "timedOut": 1,
        "cancelled": 1
      }
    }
  ],
  "steps": [
    {
      "kind": "SetDeviceProperty",
      "name": "<name>",
      "value": {}
    }
  ]
}

fleet_CreateOperation

POST/api/v1/actions/invoke/fleet_CreateOperation

Create a fleet operation as a draft.

Request CreateFleetOperationAction

  • projectIdstringProjectId
  • namestring
    • Fleet operation name must be between 1 and 128 characters.
  • descriptionstringoptional
    • Fleet operation description must be at most 4096 characters.
  • enrollmentstringFleetOperationEnrollmentoptional

    How the operation selects its targets. Defaults to Snapshot.

    • "Snapshot"

      Select the targets once, when the operation starts.

    • "Dynamic"

      Select the targets when the operation starts and then periodically, adding devices that start to match, until the operation is closed.

  • deadlineSecsintegeroptional

    Time that each target has to finish after its release, in seconds. Targets are released during their stage's spread. A target that has not finished in time times out. Without it, targets wait for their devices indefinitely.

    • Deadline must be between 1 second and 30 days.
  • selectorobjectFleetOperationTargetSelector
    3 fields
    • deviceIdsarray<string>DeviceIdoptional

      Devices that may match. Without this field, every device of the project may match.

    • groupsobjectDeviceGroupSelectoroptional

      Group conditions that devices must satisfy.

      3 fields
      • allarray<string>DeviceGroupIdoptional

        Every listed group must be present. Empty or absent imposes no condition.

      • anyarray<string>DeviceGroupIdoptional

        At least one listed group must be present. Empty matches no devices; absence imposes no condition.

      • nonearray<string>DeviceGroupIdoptional

        Every listed group must be absent. Empty or absent imposes no condition.

    • expressionstringoptional

      Expression that devices must satisfy. It can read the variables properties and now.

      A device for which the expression produces an error is not selected. The error is recorded as a selection error.

      • Expressions must be at most 4096 characters.
  • stagesarray<object>RolloutStage

    Stages in the order of their release.

    • A fleet operation must have between 1 and 20 stages.
    5 fields
    • namestring
      • Stage name must be between 1 and 128 characters.
    • groupsobjectDeviceGroupSelectoroptional

      Group conditions that the stage's devices satisfy. Without conditions, every device satisfies them.

      3 fields
      • allarray<string>DeviceGroupIdoptional

        Every listed group must be present. Empty or absent imposes no condition.

      • anyarray<string>DeviceGroupIdoptional

        At least one listed group must be present. Empty matches no devices; absence imposes no condition.

      • nonearray<string>DeviceGroupIdoptional

        Every listed group must be absent. Empty or absent imposes no condition.

    • percentagenumberoptional

      Share of the devices that satisfy the conditions, by their position in the rollout, in percent. May have a fraction, such as 0.5. Defaults to 100.

      A device belongs to the first stage whose conditions it satisfies and whose percentage is above its position.

      • Stage percentage must be greater than 0 and at most 100.
    • spreadSecsintegeroptional

      Time over which the stage's devices become active, in seconds. Defaults to 0.

      • Spread must be at most 30 days.
    • guardobjectRolloutGuardoptional

      Conditions for releasing the stage. The first stage is released when the rollout starts and ignores its guard.

      3 fields
      • minCompletedPercentnumberoptional

        Minimal share of the devices in earlier stages that completed, in percent. Defaults to 100.

        • Completed share must be between 0 and 100.
      • maxFailedPercentnumberoptional

        Maximal share of the devices in earlier stages that failed, in percent. Defaults to 0.

        • Failed share must be between 0 and 100.
      • soakSecsintegeroptional

        Minimal time since the previous stage's spread finished, in seconds. Defaults to 0.

        • Soak time must be at most 30 days.
  • stepsarray<object>DeviceOperationStep

    Steps that each target runs.

    • A fleet operation must have between 1 and 64 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 CreateFleetOperationOutput

  • fleetOperationIdstringFleetOperationId

Example

curl --fail-with-body \
  -H "Authorization: Bearer $NEXIGON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "<project-id>",
    "name": "<name>",
    "selector": {},
    "stages": [
      {
        "name": "<name>"
      }
    ],
    "steps": [
      {
        "kind": "SetDeviceProperty",
        "name": "<name>",
        "value": {}
      }
    ]
  }' \
  $NEXIGON_HUB_URL/api/v1/actions/invoke/fleet_CreateOperation
{
  "fleetOperationId": "<fleet-operation-id>"
}

fleet_PreviewOperationTargets

POST/api/v1/actions/invoke/fleet_PreviewOperationTargets

Preview the devices that a target selector currently matches.

A preview does not decide the targets of an operation. An operation selects its targets when it starts and, if it is dynamic, periodically afterwards.

Request PreviewFleetOperationTargetsAction

  • projectIdstringProjectId
  • selectorobjectFleetOperationTargetSelector
    3 fields
    • deviceIdsarray<string>DeviceIdoptional

      Devices that may match. Without this field, every device of the project may match.

    • groupsobjectDeviceGroupSelectoroptional

      Group conditions that devices must satisfy.

      3 fields
      • allarray<string>DeviceGroupIdoptional

        Every listed group must be present. Empty or absent imposes no condition.

      • anyarray<string>DeviceGroupIdoptional

        At least one listed group must be present. Empty matches no devices; absence imposes no condition.

      • nonearray<string>DeviceGroupIdoptional

        Every listed group must be absent. Empty or absent imposes no condition.

    • expressionstringoptional

      Expression that devices must satisfy. It can read the variables properties and now.

      A device for which the expression produces an error is not selected. The error is recorded as a selection error.

      • Expressions must be at most 4096 characters.
  • limitintegeroptional

    Maximum number of devices and errors to return. Defaults to 20.

    • Limit must be between 1 and 1000.

Response PreviewFleetOperationTargetsOutput

  • matchingCountinteger

    Number of matching devices.

  • devicesarray<object>QueryProjectDevicesItem

    Newest matching devices, up to the requested limit.

    10 fields
    • 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
    • deviceIdstringDeviceId

      ID of the device.

    • namestringoptional

      Name of the device.

    • hostnamestringoptional

      Hostname reported by the device (from dev.nexigon.system.info).

    • firstSeenstring (date-time)Timestamp

      Timestamp when the device was first seen.

    • statusstringDeviceStatus

      Combined device status (connection + health).

      • "healthy"

        Device is healthy and connected.

      • "warning"

        Device is connected but experiencing degraded performance.

      • "error"

        Device is connected but in an error state.

      • "offline"

        Device is not connected.

    • isConnectedboolean

      Indicates whether the device is online.

    • pendingCertificatesCountinteger

      Pending device certificates.

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

  • errorCountinteger

    Number of devices for which the expression produced an error.

  • selectionErrorsarray<object>DeviceSelectionError

    Devices for which the expression produced an error, up to the requested limit.

    2 fields
    • deviceIdstringDeviceId
    • errorstring

Example

curl --fail-with-body \
  -H "Authorization: Bearer $NEXIGON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"<project-id>","selector":{}}' \
  $NEXIGON_HUB_URL/api/v1/actions/invoke/fleet_PreviewOperationTargets
{
  "matchingCount": 1,
  "devices": [
    {
      "groups": [
        {
          "groupId": "<device-group-id>",
          "projectId": "<project-id>",
          "name": "<name>"
        }
      ],
      "deviceId": "<device-id>",
      "firstSeen": "2026-01-01T12:00:00Z",
      "status": "healthy",
      "isConnected": true,
      "pendingCertificatesCount": 1
    }
  ],
  "errorCount": 1,
  "selectionErrors": [
    {
      "deviceId": "<device-id>",
      "error": "<error>"
    }
  ]
}

fleet_StartOperation

POST/api/v1/actions/invoke/fleet_StartOperation

Start a draft fleet operation.

Selects the targets and releases the first stage.

Request StartFleetOperationAction

  • fleetOperationIdstringFleetOperationId

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 '{"fleetOperationId":"<fleet-operation-id>"}' \
  $NEXIGON_HUB_URL/api/v1/actions/invoke/fleet_StartOperation
{}

fleet_HaltOperation

POST/api/v1/actions/invoke/fleet_HaltOperation

Halt a running fleet operation.

The operation selects no targets, releases no stages, and hands out no work until it is resumed. Devices can still report the results of work that they already claimed. The clocks of spreads, soak times, timeouts, and deadlines do not advance while the operation is halted. Halting a halted operation has no effect.

Request HaltFleetOperationAction

  • fleetOperationIdstringFleetOperationId

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 '{"fleetOperationId":"<fleet-operation-id>"}' \
  $NEXIGON_HUB_URL/api/v1/actions/invoke/fleet_HaltOperation
{}

fleet_ResumeOperation

POST/api/v1/actions/invoke/fleet_ResumeOperation

Resume a halted fleet operation where it stopped.

Resuming a running operation has no effect.

Request ResumeFleetOperationAction

  • fleetOperationIdstringFleetOperationId

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 '{"fleetOperationId":"<fleet-operation-id>"}' \
  $NEXIGON_HUB_URL/api/v1/actions/invoke/fleet_ResumeOperation
{}

fleet_ReleaseOperationStage

POST/api/v1/actions/invoke/fleet_ReleaseOperationStage

Release the next stage of a running fleet operation, skipping its guard and the wait for the previous stage's spread.

Request ReleaseFleetOperationStageAction

  • fleetOperationIdstringFleetOperationId
  • stageIndexinteger

    Index of the stage to release, which must be the next unreleased one.

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 '{"fleetOperationId":"<fleet-operation-id>","stageIndex":1}' \
  $NEXIGON_HUB_URL/api/v1/actions/invoke/fleet_ReleaseOperationStage
{}

fleet_CloseOperation

POST/api/v1/actions/invoke/fleet_CloseOperation

Stop a dynamic fleet operation from selecting further targets.

The operation finishes once all of its stages are released and all of its targets have finished.

Request CloseFleetOperationAction

  • fleetOperationIdstringFleetOperationId

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 '{"fleetOperationId":"<fleet-operation-id>"}' \
  $NEXIGON_HUB_URL/api/v1/actions/invoke/fleet_CloseOperation
{}

fleet_CancelOperation

POST/api/v1/actions/invoke/fleet_CancelOperation

Cancel a fleet operation and its unfinished targets.

Request CancelFleetOperationAction

  • fleetOperationIdstringFleetOperationId

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 '{"fleetOperationId":"<fleet-operation-id>"}' \
  $NEXIGON_HUB_URL/api/v1/actions/invoke/fleet_CancelOperation
{}

fleet_QueryOperationTargets

POST/api/v1/actions/invoke/fleet_QueryOperationTargets

List the targets of a fleet operation, by stage.

Request QueryFleetOperationTargetsAction

  • fleetOperationIdstringFleetOperationId
  • statusstringDeviceOperationStatusoptional

    Only targets with this 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.

  • pageobjectPageRequestoptional

    Page to return. Without this field, the first page is returned.

    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.

Response QueryFleetOperationTargetsOutput

  • targetsarray<object>FleetOperationTarget

    Targets on this page, by stage.

    10 fields
    • deviceIdstringDeviceId
    • deviceOperationIdstringDeviceOperationId

      Device operation that runs the steps on the device.

    • stageIndexinteger

      Index of the target's stage.

    • stepIndexinteger

      Index of the step that the target is at.

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

    • lastErrorstringoptional
    • releasedAtstring (date-time)Timestampoptional

      Time when the target was released, during its stage's spread. Absent until then.

    • deadlineAtstring (date-time)Timestampoptional

      Time when the target times out unless it has finished.

    • updatedAtstring (date-time)Timestamp
    • stepStatesarray<object>DeviceOperationStepState

      States of the steps that the target has reached. Correlate them with FleetOperationDetails.steps by step_index.

      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.

  • pageobjectPageInfo

    Continuation of the traversal.

    1 field
    • nextCursorstringPageCursoroptional

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

Example

curl --fail-with-body \
  -H "Authorization: Bearer $NEXIGON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"fleetOperationId":"<fleet-operation-id>"}' \
  $NEXIGON_HUB_URL/api/v1/actions/invoke/fleet_QueryOperationTargets
{
  "targets": [
    {
      "deviceId": "<device-id>",
      "deviceOperationId": "<device-operation-id>",
      "stageIndex": 1,
      "stepIndex": 1,
      "status": "Pending",
      "updatedAt": "2026-01-01T12:00:00Z",
      "stepStates": [
        {
          "stepIndex": 1,
          "status": "Pending"
        }
      ]
    }
  ],
  "page": {}
}

fleet_QueryOperationSelectionErrors

POST/api/v1/actions/invoke/fleet_QueryOperationSelectionErrors

List the devices for which a fleet operation's target selector produced an error.

Request QueryFleetOperationSelectionErrorsAction

  • fleetOperationIdstringFleetOperationId

Response QueryFleetOperationSelectionErrorsOutput

  • errorsarray<object>FleetOperationSelectionError
    3 fields
    • deviceIdstringDeviceId
    • errorstring

      Error that the expression produced.

    • updatedAtstring (date-time)Timestamp

      When the error was last observed.

Example

curl --fail-with-body \
  -H "Authorization: Bearer $NEXIGON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"fleetOperationId":"<fleet-operation-id>"}' \
  $NEXIGON_HUB_URL/api/v1/actions/invoke/fleet_QueryOperationSelectionErrors
{
  "errors": [
    {
      "deviceId": "<device-id>",
      "error": "<error>",
      "updatedAt": "2026-01-01T12:00:00Z"
    }
  ]
}