Devices API

List, retrieve, update, and delete devices via the REST API.

Written By Erdinc Akay

Last updated 8 days ago

The Devices API lists, retrieves, updates, and deletes devices. Note: all device endpoints use the path prefix /api/assets. The term "asset" is used internally in the backend; the UI and documentation refer to these as devices.

For the complete, always-current list of endpoints, parameters, and response fields for the version you are running, use the interactive OpenAPI (Swagger) interface at https://<your-octoja-instance>/openapi/index.html.

Endpoints

OperationEndpointNotes
List devicesGET /api/assetsReturns a paginated { items, total } envelope of device headers. Default sort is LastSeen descending; override with sortBy / sortDir. pageSize is capped at 100 (default 25).
Get a deviceGET /api/assets/{id}Returns { asset, assetData, updatedAt, settings, canBypassRemoteDesktopConsent } — the device header plus the full inventory snapshot (hardware, installed software, running services, pending OS updates, local users, network adapters) and when it was last received from the agent. See the Notes below the table.
Update a devicePOST /api/assets/{id}The caller's group must hold the per-device Edit Device grant for the device. Uses the UpdateValue<T> envelope — see below.
Delete a deviceDELETE /api/assets/{id}The caller's group must hold the per-device Delete Device grant for the device. See deletion behaviour below.

Note on the Get response: settings carries the per-device agent settings (each with its effective value, any per-device override, and which config packages enable it), and canBypassRemoteDesktopConsent reflects the caller's own permission rather than a device setting. See Swagger for the full field-by-field shape.

Note on permissions: updating and deleting a device use octoja's per-device action grants — the Edit Device and Delete Device grants your group holds for that specific device — not a single global permission. Group access controls which devices each grant applies to.

Updating a device

All update fields are optional — only send the fields you want to change. Each field is wrapped in an UpdateValue<T> envelope of the shape { "hasValue": true, "value": <T> }; omit a field entirely to leave it untouched. A bare value (for example "deviceAlias": "web-01") does not bind. Use { "hasValue": true, "value": null } to clear a value.

{  "deviceAlias": { "hasValue": true, "value": "web-01" },  "customerId": { "hasValue": true, "value": null }}

The updatable fields are deviceAlias, customerId, customerSiteId, tags, and deviceKind (Swagger has their exact types). A few behaviours and validations are not visible in the schema:

  • deviceAlias — trimmed, max 100 characters; a null value clears the alias.
  • customerId — a null value unassigns the customer. Reassigning the customer resets the stored customerSiteId to null; send customerSiteId in the same request if the device should keep its site assignment.
  • customerSiteId — requires an effective customer: either the incoming customerId or the device's currently-stored customerId must be non-null.
  • tags — replaces user-defined tags only; inventory-derived tags are always preserved and cannot be removed through the API. Max 50 tags, 100 characters each.
  • deviceKind — overrides the classified device kind. It is one of a fixed set of values (see Swagger); an invalid value returns 400 Bad Request.

The update endpoint also accepts five per-device agent-setting overrides. Each is a nullable boolean where true forces the setting on, false forces it off, and null clears the override so the device inherits the value from its config packages:

  • requiresRemoteDesktopConsent — require the signed-in user to consent before a remote-desktop session starts.
  • showAgentInTray — show the agent icon in the system tray.
  • softwareKioskEnabled — enable the self-service software kiosk.
  • ticketingEnabled — enable ticket creation from the device.
  • autoLockOnDisconnect — automatically lock the device when a remote-desktop session disconnects.

Deleting a device

Removes the device from octoja — it no longer appears in the device list and cannot be retrieved through the API. The associated agent record is also deleted and the agent's realtime connection is severed immediately. The agent software must be uninstalled separately on the device.

Device fields worth knowing

The full device object is documented field-by-field in Swagger. A few fields carry behaviour that is easy to miss:

  • checkStatus — a summary of the device's checks ({ total, ok, warning, critical, details }, where details is an array of { name, status } entries). Only populated on the list endpoint; always null on GET /api/assets/{id}.
  • tags — an array of { value, source }, where source is Inventory (auto-assigned by the agent from hardware and software, not editable via the API) or User (set manually via the update endpoint or the UI).
  • lywandScore — the latest Lywand security score, or null when the device is not matched to the Lywand integration.
  • allowedActions — an array of the device actions your group grants you on this specific device, as action names (for example ["RemoteDesktop", "Terminal", "EditAsset"]). It is scoped to the calling user — two callers can see the same device with different allowedActions — and is returned on both the list and the Get responses. An empty array means you can see the device but have no granted operations on it (view-only). EditAsset and DeleteAsset in this array are what gate the update and delete endpoints for that device.
  • deviceKind — the classified device kind, one of a fixed set of values (see Swagger).