Actions API

The Actions API is Nexigon Hub’s interface for querying data, managing resources, and starting workflows. Each action has a name, an input type, and an output type. HTTP clients invoke actions with JSON requests; Nexigon CLI and the SDKs use the same contracts.

Use the Nexigon Hub API reference to find an action’s exact input and output fields. The OpenAPI definitions are available for client generation.

HTTP

Each action accepts a POST request at /api/v1/actions/invoke/<action-name>. The body is the action’s JSON input. Authenticate with a user or organization API token. Devices invoke actions through Nexigon Agent instead, as described in Compatibility.

Set the NEXIGON_TOKEN shell variable to your user or organization API token. For example, inspect the authenticated identity:

curl --fail-with-body \
  -H "Authorization: Bearer $NEXIGON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}' \
  https://eu.nexigon.cloud/api/v1/actions/invoke/actor_GetActor

Use your own Nexigon Hub URL if it differs. A successful response contains an actor identifying the token and its owning user or organization.

Organization Scope

The optional X-Nexigon-Organization: <org-id> header restricts resource operations to one organization. For example, list its projects:

curl --fail-with-body \
  -H "Authorization: Bearer $NEXIGON_TOKEN" \
  -H "X-Nexigon-Organization: <org-id>" \
  -H "Content-Type: application/json" \
  -d '{"organizationId":"<org-id>"}' \
  https://eu.nexigon.cloud/api/v1/actions/invoke/organizations_QueryProjects

A resource outside the selected organization is treated as missing: ID-based lookups return NotFound with HTTP 404. Path resolvers use their existing NotFound result. The header restricts access without granting permissions. Instance-wide actions require an unscoped request.

For user tokens, omitting the header leaves requests unscoped. Organization API tokens are always restricted to their own organization. A header supplied with an organization token must match its organization. Invalid IDs, multiple header values, or a conflicting organization produce HTTP 400.

For WebSocket clients, set the header on the handshake. The selected organization applies to the connection’s action and forwarding channels. Nexigon CLI’s unreleased organization-selection commands use this mechanism; see Authentication and Organization Selection.

Responses and Errors

HTTP 200 means the response conforms to the action’s output type. That output can include an expected application error, such as an already-existing resource. Inspect the action result even when the HTTP request succeeds.

For example, repositories_CreatePackage returns one of these results, both with HTTP 200. Creating a new package returns its ID:

{ "result": "Created", "packageId": "<package-id>" }

If its name is already taken in that repository, the response is:

{ "result": "NameAlreadyExists" }

The second response means no package was created. A client must inspect the result field to decide whether to continue with the existing package or choose another name; checking the HTTP status alone misses that distinction.

HTTP 4xx and 5xx statuses indicate errors outside that output contract, such as invalid input, insufficient permission, or an internal failure. Nexigon Hub returns a structured error envelope, for example:

{
  "error": "Forbidden",
  "message": "Actor does not have the required permissions."
}

A proxy or load balancer may return another format. Clients must handle non-JSON error responses.

Action Contracts

Action names combine a namespace and an operation name, for example organizations_Query or devices_QueryEvents. An invocation is one call with a concrete input. The authenticated entity making the call is its actor, such as a user or device.

Sidex defines input and output types. Those definitions generate Rust and TypeScript types, JSON Schema, and the OpenAPI specification. Actions are defined independently of their transport; HTTP supplies the URL, headers, and response status.

Error Categories

Compatibility

Actions can change in backward-incompatible ways between Nexigon Hub releases, but such changes are rare. The actions of two APIs deviate from this:

Devices often run the same Nexigon Agent release for years. The Device API covers the actions they need, so that agents keep working with newer Nexigon Hub releases. Nexigon Agent invokes these actions with the device as the actor; software on a device uses the agent’s commands, such as nexigon-agent device properties set. A device can invoke other actions it has permission for, but only Device API actions carry the long-term promise. Users and integrations can invoke Device API actions as well, for example, devices_GetProperty to read a device property.

Pagination

Project device listings (projects_QueryDevices), device events, and audit logs support cursor pagination. A cursor is an opaque token that identifies where to continue a query.

Fetching Successive Pages

Invoke devices_QueryEvents with:

{
  "deviceId": "<device-id>",
  "page": { "limit": 100 }
}

The response contains events and page. If page.nextCursor is present, pass it unchanged to the same action and device:

{
  "deviceId": "<device-id>",
  "page": { "limit": 100, "cursor": "<previous-page.nextCursor>" }
}

Continue until page.nextCursor is absent. Page length alone does not indicate the end. A cursor continues only the action, scope, and filter that produced it, so start without a cursor when changing any of them. The limit can change between requests.

Supported Actions and Limits

Pagination is supported by projects_QueryDevices, repositories_QueryPackageVersions, repositories_QueryPackageTags, devices_QueryEvents, devices_QueryAuditLog, projects_QueryAuditLog, repositories_QueryAuditLog, organizations_QueryAuditLog, audit_QueryAuditLogEvents, and audit_QueryAuditLogActions. Device listing responses use devices, version listings versions, tag listings tags, and audit action responses actions instead of events.

Device, version, and tag listings and device events default to 100 entries per page, audit queries to 200 entries. Page sizes must be positive and cannot exceed the operator-configured maximum, which defaults to 1000. A lower configured maximum also caps the endpoint default.

projects_QueryDevices, repositories_QueryPackageVersions, and repositories_QueryPackageTags always return a single page. Without page, they return the first page with the default size, so clients that need every entry must follow page.nextCursor. The other actions omit page metadata for requests without page and retain their unpaginated behavior. Device events also accept the legacy top-level limit, which cannot be combined with page.limit. Listing Devices describes the filter of device listings.

Ordering and Consistency

Devices are ordered by the time they were first seen, newest first. Package versions are ordered by creation time and tags by the time they were assigned, newest first. Device events are ordered by emission time, newest first. Audit entries are ordered by creation time, newest first. Equal timestamps have a deterministic tie-breaker.

Each request reads current data. Delayed events, retention, and changes to devices, versions, or tags can change the result between pages. A cursor remains usable after its boundary entry is deleted. Starting without a cursor reads from the newest entries. Pagination does not provide a frozen export or a lossless subscription to new entries.

Cursor Authentication

Each request requires the usual permissions. Clients must treat cursors as opaque tokens. A malformed, altered, or incompatible cursor produces an Invalid action error and requires a fresh traversal. Server key or cursor size limit changes can invalidate existing cursors.