NetLock RMMNetLock RMM Docs
V — Appendix

Public API

The REST API of the server: tokens, scopes and rate limits in brief, where the Swagger reference lives, the custom field endpoints with level values and effective values, and the automation rules.

Public API

The server exposes a REST API under /v1 for external systems: a PSA, a CMDB, a documentation tool, an automation pipeline. This appendix explains how access works and documents the custom field endpoints and the automation rules in detail, because they carry rules the generated reference does not spell out. Every other endpoint is documented in the Swagger reference served by the server itself.

X.9.1 Access in brief

Switches. Settings → API tokens (route /settings/api-tokens) holds two deployment-wide switches: Public API enabled and Public API documentation enabled. The server re-reads the API switch about once a minute; no restart is needed. The documentation switch covers only /docs and the OpenAPI document.

Reference. With the documentation enabled, the server serves a Swagger UI at https://<server>/docs and the OpenAPI document at https://<server>/openapi/v1.json. Every route carries a summary and a description with its body shape, its scope and the permissions it needs. That page is the authoritative reference for request and response shapes.

Tokens. A token is created on the same page and shown once. It has the form nlk_<key id>_<secret> and is sent as a Bearer token:

Authorization: Bearer nlk_0123456789ab_...

A token is bound to a console account and carries:

  • Scopes such as customfields:read or devices:actions:script. Only scopes whose underlying permissions the bound account holds are offered, and the account's permissions are checked again on every request. A token never has more rights than its account.
  • Tenants: the tenants selected for the token plus the tenants the token created itself through the API, limited to what its account holds. With the option All tenants of the account they are the tenants of the account, evaluated on every request. A token can additionally be narrowed to a list of locations. A device, tenant, location or group outside that scope answers 404. See X.9.11.
  • A rate limit in requests per minute (default 600). Requests above it answer 429 with a Retry-After header. Independent of the token, one IP address is capped at 1200 requests per minute and at 20 failed authentications per minute.
  • An expiry date, or none. Tokens can be rotated and revoked from the same page.

Errors. Errors are JSON problem documents with a code, for example insufficient_scope (the token lacks the scope), insufficient_permission (the bound account lacks a permission), location_restricted (the token is limited to locations), invalid_parameter, not_found and rate_limited. The report codes sql_access_not_configured and sql_invalid are described in X.9.16.

Audit. Writes through the API are written to the audit log with the token name.

Idempotency. Actions that change something accept an Idempotency-Key header. Sending the same key again for the same request returns the first response for 24 hours instead of running the action a second time. A key belongs to one request path: the same key sent to another path, for example the same action for another device, answers 409 idempotency_key_reuse. Use one key per device and action. A request that is still running answers 409 idempotency_key_in_flight.

Updates. Update the Web Console first, then the server. The Web Console updates the database that the server's API relies on.

X.9.2 Endpoint groups

The API covers the organization (tenants, locations, groups); devices with their inventory, enrolment, antivirus state, processes, event logs, files and registry; device actions (power, sync, commands and scripts, agent uninstall); mobile devices; events, alerts and notification results; external references; device usage per tenant; custom fields; patch management and vulnerabilities; sensors, SNMP, uptime monitoring and the port scanner; software deployments and App Hub; scripts and jobs; policies, automations and maintenance windows; notification targets; the file server; tickets and time tracking; users and permissions; the audit log; reports and dashboards; relay sessions; outbound webhooks; application control, device control and controlled folder access; BitLocker; agent packages and installer links; and the platform's own health and licence state. See the Swagger reference for each of them.

X.9.3 Custom fields

Scope customfields:read for the reads and customfields:write for the writes. Every write in addition needs the permission collections_custom_fields_edit on the bound account; the global level needs settings_custom_fields_enabled for reads and writes. For the concepts (levels, inheritance, secrets) see Chapter 8.4.

Definitions

GET /v1/custom-fields returns the definition catalogue, paginated: id, name, description, author, createdAt and the definition document with its tabs, sections and fields. Definitions are global and not tenant scoped. Definitions cannot be created or changed over the API.

Device values

GET /v1/devices/{id}/custom-fields returns the rows stored on the device itself:

{
  "deviceId": 42,
  "items": [
    { "definitionId": 3, "definitionName": "AV", "fieldKey": "av_ou_id", "value": "ou-dev", "isSecret": false, "source": "api", "updatedAt": "2026-09-04T10:15:00Z" },
    { "definitionId": 3, "definitionName": "AV", "fieldKey": "av_token", "value": null, "isSecret": true, "source": "manual", "updatedAt": "2026-09-04T09:00:00Z" }
  ]
}
  • source names who wrote the device value last: manual (console), script (write-back from a script) or api.
  • isSecret is true for a Secret field; its value is always null.
  • A field the device has no row for is not listed. A value cleared in the console has no row either.

GET /v1/devices/{id}/custom-fields?effective=true returns one item per manual field of every definition with the value the device effectively reads, resolved the way a script variable is resolved: the device's own value first, then, for an inheritable field, the group, location, tenant and global value in that order.

{
  "deviceId": 42,
  "items": [
    { "definitionId": 3, "definitionName": "AV", "fieldKey": "av_ou_id", "value": "ou-123", "isSecret": false, "inheritable": true, "level": "tenant", "source": null, "updatedAt": "2026-09-04T10:15:00Z", "updatedBy": "ansible-token" },
    { "definitionId": 3, "definitionName": "AV", "fieldKey": "laps_status", "value": "windows-laps", "isSecret": false, "inheritable": false, "level": "device", "source": "script", "updatedAt": "2026-09-04T11:00:00Z", "updatedBy": null },
    { "definitionId": 4, "definitionName": "Notes", "fieldKey": "note", "value": null, "isSecret": false, "inheritable": false, "level": "none", "source": null, "updatedAt": null, "updatedBy": null }
  ]
}
  • level names where the value comes from: device, group, location, tenant, global, or none when no level holds a value.
  • source is set only when level is device. updatedBy (the account or token name) is set only for a value from a level above the device.
  • Secrets are never returned, on any level.

PUT /v1/devices/{id}/custom-fields sets device values:

{ "values": { "3:av_ou_id": "ou-dev", "3:note": null } }

The key of each entry is <definitionId>:<fieldKey>. null clears the value; the row is deleted, so the device inherits again. A value for a Secret field is stored encrypted. Stored values get source: api, the device is marked for a policy re-sync, and when an automation rule compares one of the fields, the rules are evaluated for the device and it is pushed at once if its assignment changed. The definition must exist. The answer is the device read back in the shape of the GET. The same values can be sent as customFields in PATCH /v1/devices/{id}.

Level values

One pair of routes per level, all with the same body and answer shape:

LevelRoutesVisible when
GlobalGET, PUT /v1/custom-fields/globalAlways; needs settings_custom_fields_enabled
TenantGET, PUT /v1/tenants/{id}/custom-fieldsThe tenant is in the token's tenant scope
LocationGET, PUT /v1/locations/{id}/custom-fieldsThe location is in the token's tenant scope and, when the token is limited to locations, in that list
GroupGET, PUT /v1/groups/{id}/custom-fieldsAs for its location

A level outside the scope answers 404. GET returns the rows stored on this level:

{
  "scopeType": "tenant",
  "scopeId": 5,
  "items": [
    { "definitionId": 3, "definitionName": "AV", "fieldKey": "av_ou_id", "value": "ou-123", "isSecret": false, "stale": false, "updatedAt": "2026-09-04T10:15:00Z", "updatedBy": "ansible-token" },
    { "definitionId": 3, "definitionName": "AV", "fieldKey": "av_token", "value": null, "isSecret": true, "stale": false, "updatedAt": "2026-09-04T10:15:00Z", "updatedBy": "ansible-token" }
  ]
}

stale is true when the field is no longer an inheritable manual field of its definition, or the definition is gone. The row is listed anyway so it can be cleared.

PUT takes the same body as the device endpoint, { "values": { "<definitionId>:<fieldKey>": value | null } }, and answers with the level read back:

  • Only inheritable Manual fields of type Text, Multiline or Secret are accepted, and a value may not exceed 64 KB. Any other entry answers 400 invalid_parameter with the reason, and nothing of the request is written.
  • null clears the row, also a stale one.
  • A token limited to locations cannot write tenant or global values (403 location_restricted). A token without any tenant cannot write global values.
  • updatedBy is the token name. One audit entry per request names the level and the counts, never the values.
  • Every write marks the devices of the level for a policy re-sync; a global write marks every device. When an automation rule compares one of the fields, the online devices of the level are pushed at once.

Example: set the OU id for tenant 5.

curl -X PUT "https://server.example.com/v1/tenants/5/custom-fields" \
  -H "Authorization: Bearer nlk_..." \
  -H "Content-Type: application/json" \
  -d '{"values":{"3:av_ou_id":"ou-123"}}'

X.9.4 Device actions and script variables

POST /v1/devices/{id}/actions/run-script (body { "scriptId" } or { "scriptName" }, optional runAsUser; scope devices:actions:script) and POST /v1/devices/{id}/actions/run-command (body { "command", "language", "runAsUser", "timeoutMinutes" }; scope devices:actions:shell) render script variables for the target device before the command is sent, in the shell named by language or the device's platform default. cmd is not rendered.

The action record and GET /v1/device-actions/{id} keep the unrendered text, so a resolved secret never appears in an API answer. The result is the output with write-back marker lines removed; their values are stored on the device.

Every completed command also writes an event Remote shell command executed. (type Remote Shell) on the device that names the token, the action, the run-as user and the shell and carries the output; the command text is not part of it. GET /v1/device-actions/{id} reads the shell output from the action record; result and output hold the same text for shell actions. Both actions exist as /v1/devices/bulk/actions/run-script and /v1/devices/bulk/actions/run-command as well.

POST /v1/sensors/{id}/test renders the sensor's scripts for the target device in the same way. Values the scripts would write back are listed as Would set: <keys> in the additional details and are not stored.

POST /v1/devices/{id}/files/actions/collect (scope devices:remote-files:read) needs agent 3.3.0.6 or later on the device; with an older agent the action ends with a failed result.

See Script variables and custom fields in scripts and Write custom field values from a script.

X.9.5 Automations

Scope automations:read for the reads and automations:write for the writes. For the model (conditions, negation, priority, the enabled switch, how the server picks a device's policy and how sensors and jobs are added), see Chapter 5.

Reading rules

GET /v1/automations lists the rules, ordered by priority then id unless sorted otherwise (sort=priority, sort=-priority, sort=name, …), with the filters tenantId, deviceId, enabled (true/false), sensorId, jobId (rules that add that sensor or job) and search. GET /v1/automations/{id} returns one rule. Both return:

{
  "id": 13,
  "name": "Linux in ACME",
  "description": "",
  "enabled": true,
  "priority": 600,
  "policyName": "Linux base",
  "sensorIds": [7, 9],
  "jobIds": [],
  "conditions": [
    { "type": "tenant", "negate": false, "tenantId": 5, "name": "ACME" },
    { "type": "platform", "negate": false, "values": ["Linux"] },
    { "type": "device_attribute", "negate": true, "field": "device_name", "op": "wildcard", "value": "SRV-*" }
  ],
  "deviceId": null, "tenantId": 5, "locationId": null, "groupId": null,
  "effectiveTenantId": 5,
  "author": "admin@example.com",
  "createdAt": "2026-09-16T10:21:27Z"
}
  • conditions is the rule's condition list as stored. Every entry has type and negate; an entity condition carries its id (deviceId, tenantId, locationId or groupId) and the entity's name; internal_ip and domain carry value; platform carries values; device_attribute carries field, op and value.
  • A location or group condition additionally carries locationIds / groupIds and names in the same order (null for an entity that is gone or outside the token's tenants). It may name several entities ("is one of"); then locationId / groupId and name are null and only the lists carry the entries: { "type": "group", "negate": false, "groupId": null, "name": null, "groupIds": [12, 17, 23], "names": ["No print", "No print", "No print"] }. For a single entity both forms are filled.
  • policyName is null for a rule that assigns no policy. sensorIds and jobIds are the sensors and jobs the rule adds to every matching device on top of its policy.
  • deviceId, tenantId, locationId and groupId on the rule itself mirror the non-negated entity conditions that name one entity; a rule whose location or group condition names several carries the tenant of those entities in tenantId; effectiveTenantId is the tenant the rule belongs to, or null for a rule without an entity condition. Such a rule is instance wide and is returned to every token holding the scope.
  • A rule is returned only when the tenant it resolves to is inside the token's tenant scope.

From 3.3.0.4, policyName replaces trigger; condition, expectedResult, actions, category and subCategory are not returned.

Writing rules

POST /v1/automations creates a rule, POST /v1/policies/{id}/assign creates a rule for the policy named by the route, PATCH /v1/automations/{id} changes one, DELETE /v1/automations/{id} removes one. The create body:

{
  "name": "Linux in ACME",
  "description": "optional",
  "policyName": "Linux base",
  "sensorIds": [7, 9],
  "jobIds": [],
  "enabled": true,
  "priority": 600,
  "conditions": [
    { "type": "tenant", "tenantId": 5 },
    { "type": "platform", "values": ["Linux"] },
    { "type": "device_attribute", "field": "device_name", "op": "wildcard", "value": "SRV-*", "negate": true }
  ]
}
  • conditions needs at least one entry; all have to hold. Each entry may carry negate: true. At most one non-negated condition per entity type is allowed. Types and fields:

    • device { deviceId }, tenant { tenantId }, location { locationId }, group { groupId }.
    • internal_ip { value }, domain { value }.
    • platform { values[] } with Windows, Linux, MacOS, Android, iOS.
    • device_attribute { field, op, value } with field one of device_name, operating_system, label, serial_number, device_class, architecture, manufacturer, model, mainboard, cpu, gpu, agent_version, last_active_user, timezone, antivirus_solution and op one of eq, contains, starts_with, wildcard, regex.
    • service { field, op, value, status } with field name or display_name, op eq, contains or wildcard and status any, running or stopped (a Linux unit matches with or without .service).
    • application { op, value, versionOp?, version? } with versionOp eq, gte, lt or starts_with.
    • custom_field { key, op, value? } with key the field key of a custom field definition and op eq, contains, regex or is_empty.

    A location or group condition may send locationIds[] / groupIds[] (up to 500) instead of locationId / groupId. The condition holds when the device is in any of them; negated, it holds when the device is in none of them. Send either the single id or the list; sending both answers 400, and so do deviceIds and tenantIds. A list with one id is stored as the single id. Every id has to be inside the token's tenant scope (otherwise 404); all ids of one condition have to belong to the same tenant and lie inside the tenant or location the rule names elsewhere (otherwise 400).

    A pattern that does not compile, an unknown platform, field, operator or status, a missing value or version, a key no definition carries or a secret field answers 400 invalid_parameter with the entry named. Service, application and custom field conditions are evaluated on the server against the device's last inventory upload (see Chapter 5.2.2).

  • A rule needs at least one action: policyName (an existing policy; on /v1/policies/{id}/assign the route names it), sensorIds or jobIds; a body with none of them answers 400. sensorIds and jobIds are lists of existing ids; an unknown id, or a sensor the SNMP discovery manages, answers 400 invalid_parameter naming the field. The items are added to every matching device on top of its policy and are handed out only to devices that have a policy. enabled defaults to true. priority defaults to the most specific organisation condition (device 100, internal IP 200, domain 300, group 400, location 500, tenant 600, otherwise 700) and may be any number from 0.

  • Every entity a condition names has to be inside the token's tenant scope; one outside answers 404, as reading it would. A rule with no non-negated entity condition matches in every tenant and is accepted only when the token's scope covers every tenant of the instance.

  • PATCH has merge-patch semantics on name, description, policyName, enabled, priority, conditions, sensorIds and jobIds: a field left out stays as it is; conditions, sensorIds and jobIds each replace their whole list ([] empties it). policyName: null removes the policy; it is refused when the rule would be left without any action.

  • The answer of a create or change is { id, created | updated, policyName, sensorIds[], jobIds[], enabled, priority, conditions[] } with the conditions in the read shape (entity names resolved). A create answers 201; send an Idempotency-Key header to make a retry safe.

  • Every write marks the affected devices out of sync and queues an acceleration request, so online devices re-sync right away.

A single-condition body is accepted as well. { "condition": "tenant" | "location" | "group" | "device" | "internal-ip" | "domain", "tenantId" | "locationId" | "groupId" | "deviceId" | "value": … } is translated into one condition and stored in the list form; the answer is the list form. A request that sends both conditions and the single-condition fields answers 400. On PATCH, the single-condition fields replace the whole condition list with that one condition: a PATCH { "tenantId": 7 } on a rule with three conditions leaves it with the one tenant condition; send conditions to change one entry of a list.

Policies. POST /v1/policies creates a policy with the same default settings the console's policy editor starts with; the answer is { id, created, defaultsApplied }. defaultsApplied is false when the Web Console has not started yet on this instance; the policy is then created without settings. On PUT /v1/policies/{id}/settings, a section that is left out or null takes the default setting instead of being cleared; the answer lists those sections in sectionsDefaulted (field names, like sectionsSet). Only if the Web Console has not started yet on this instance does such a section stay unset; sectionsCleared counts those.

DELETE /v1/policies/{id} deletes the rules that only assign the policy and keeps the rules that also add sensors or jobs, without the policy; it answers { id, deleted, assignmentsDeleted, assignmentsKept }. DELETE /v1/sensors/{id} and DELETE /v1/jobs/{id} remove the item from every rule that adds it; a rule left without any action is switched off.

Deleting a device (DELETE /v1/devices/{id}, bulk delete), a location or a group adjusts the automation rules that name it as in the Console (§5.7): a rule that still names another tenant, location, group or device is switched off, a rule left without one is deleted, and each such rule gets an audit entry under the token's account.

PATCH /v1/automations/{id} without new conditions and DELETE /v1/automations/{id} skip the ids of tenants, locations, groups or devices that no longer exist: such a condition binds the rule to no tenant, so the rule then needs a token whose scope covers every tenant, unless another condition still names an entity in the token's scope. An id that belongs to a tenant outside the token's scope still answers 404.

GET /v1/devices/{id}/sensors lists the sensors the device receives: those of its policy and those the matching automation rules add, the latter only when the device has a policy and only for the device's platform. Every entry carries source, policy or automation.

GET /v1/devices/{id} carries automationState: the decision of the device's last evaluation as { policyName, policySource, automationId, sensorIds, jobIds, matchedAutomationIds, evaluatedAt, handedOutAt }, or null before the first evaluation. policySource is automation, default or none; evaluatedAt is updated by every evaluation, handedOutAt only when the device fetched its policy. The field is left out of list rows and honours ?fields=.

Example: give every Windows device of tenant 5 the policy Windows base, ahead of the tenant's other rules.

curl -X POST "https://server.example.com/v1/automations" \
  -H "Authorization: Bearer nlk_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Windows in ACME","policyName":"Windows base","priority":550,"conditions":[{"type":"tenant","tenantId":5},{"type":"platform","values":["Windows"]}]}'

X.9.6 Labels of scripts, jobs and sensors

Scripts, jobs and sensors carry a free-text label (up to 64 characters, null when none is set), which the console groups its lists by.

  • GET /v1/scripts, /v1/jobs and /v1/sensors, the single reads and GET /v1/devices/{id}/sensors return label; it honours ?fields=.
  • The lists filter with ?label= (exact, case-insensitive), and ?search= also matches the label. Scripts and jobs sort with sort=label.
  • POST /v1/scripts, /v1/jobs and /v1/sensors accept label. On PATCH, a body without label leaves it unchanged; "" or null removes it. A longer value or a value that is not a string answers 400 invalid_parameter.
  • The label is not part of the document the agents receive: a PATCH that changes only the label does not mark any device out of sync.

X.9.7 Users and roles

Console accounts either follow a role (a named permission set, see Chapter 14.4) or carry custom permissions.

  • GET /v1/users and GET /v1/users/{id} (users:read) return role as { "id": 3, "name": "Technician", "builtIn": false }, or null for custom permissions, and roleOrigin with the name of the role a custom account was detached from (null when it never followed one). The list filters with ?role=<name>, ?role=custom and ?roleId=<int>, and sort=role sorts by the role name. Both fields honour ?fields=.
  • GET /v1/roles and GET /v1/roles/{id} (users:read) list the roles with id, name, description, builtIn, memberCount, createdAt and updatedAt; the single read also carries permissions, the same object shape as GET /v1/users/{id}/permissions. The list filters with ?builtIn= and ?search=.
  • POST /v1/users takes roleId. With roleId the account starts with that role's permissions and follows it; because that grants permissions, the token needs users:permissions:write in addition to users:write, and a role that holds a permission the bound account does not answers 409 permission_escalation_forbidden. Without roleId the account has custom permissions and none of them. The response carries role and roleOrigin.
  • PUT /v1/users/{id}/role (users:permissions:write) with { "roleId": 3 } binds the account: its permissions become the role's permission object at once and every later change of the role applies to it. { "roleId": null } detaches the account; it keeps its permissions as custom permissions and roleOrigin names the role. An unknown roleId answers 404; the self-edit and escalation refusals of the permissions write apply.
  • PUT /v1/users/{id}/permissions detaches an account that follows a role: the permissions written become its own, role is null afterwards and roleOrigin names the role.
  • PATCH /v1/users/{id} does not accept role. Disabling, deleting or demoting the last enabled account that holds users_enabled, users_manage and users_edit (through PATCH with enabled: false, DELETE, the permissions write or a role without those three keys) answers 409 last_user_manager.
  • From 3.3.0.5, role is an object or null; POST and PATCH reject a role field as unknown.

An account's tenant access is the switch Access to all tenants and a list of tenants (see Chapter 14.5):

  • GET /v1/users and GET /v1/users/{id} return allTenants (the account has access to all tenants, including tenants created later) and tenants as the effective list of tenant ids: every existing tenant when allTenants is true, otherwise the assigned tenants that exist. Both honour ?fields=; the list filters with ?allTenants=true|false.
  • GET /v1/users/{id}/permissions returns tenants and allTenants next to permissions, so a read-then-write round trip carries the whole tenant state.
  • POST /v1/users accepts allTenants (default false, whatever roleId is). It needs users:permissions:write like roleId, and only a token that itself reaches every tenant may set it: a token that uses All tenants of the account while that account has access to all tenants. Any other token answers 409 permission_escalation_forbidden. The response carries allTenants.
  • PUT /v1/users/{id}/permissions takes { permissions, tenants, allTenants? }. allTenants left out leaves the switch as it is, so a client that replays an earlier response does not switch an administrator off; true carries the same refusal as on POST; false is always allowed. While the switch is on, tenants is stored but not evaluated. The response carries allTenantsBefore and allTenants, and the audit entry names the switch when it changed.
  • GET /v1/me returns accountAllTenants: the bound account has access to all tenants, so tenantIds of a token with All tenants of the account is complete.
  • Update the Web Console before the server. Until then the server evaluates every account from its tenant list alone, and allTenants: true on POST or PUT answers 409 console_update_required.

X.9.8 Device country

The server resolves the country of a device's external address (ipAddressExternal) at every check-in against its bundled GeoIP database and stores it with the device (see Chapter 3.1 — Country of a device). No lookup leaves the installation.

  • GET /v1/devices, GET /v1/devices/{id}, GET /v1/mobile-devices, GET /v1/mobile-devices/{id} and GET /v1/enrollment/pending return geoCountryCode (ISO 3166-1 alpha-2, upper case) and geoCountryName (the English name from the database). Both are null for a device that connects through a private address, for an address the database has no country for, and for a device that has not checked in yet. On the device and mobile device reads they honour ?fields=.
  • GET /v1/devices filters with ?geoCountryCode=DE (exact, one code) and sorts with sort=geoCountryCode or sort=-geoCountryCode.
  • The fields are read-only; the country cannot be set through the API.

When the country restriction of the server is active, API clients are admitted by the country of their address like every other client; the token does not exempt them.

X.9.9 Server sensors and event types

Server sensors (category 12) are evaluated by the server itself; see Chapter 8.3 — Server sensors.

  • GET /v1/sensors and GET /v1/sensors/{id} return them with serverSensor { allTenants, triggers }; for every other sensor serverSensor is null. The triggers depend on the sub-category:
    • 0 Unauthorized device: new_device, reinstall, hwid_changed, license_limit. hwid_changed is the one trigger whose device stays authorized; the server only records the new hardware ID.
    • 2 Device country: outside_countries, refused, country_changed.
  • The tenants a server sensor covers are not returned; allTenants tells whether it covers every tenant, including tenants created later.
  • Server sensors are read-only through the API: POST, PUT and PATCH do not create or change them, DELETE /v1/sensors/{id} removes one. Create and change them in the Web Console.

GET /v1/events filters with ?type= on the numeric event type: 0 antivirus, 1 job, 2 sensor, 4 device uptime, 5 website uptime, 6 port scanner, 7 SNMP discovery, 8 remote shell, 10 patch management, 11 device authorization (written by server sensors of the kind Unauthorized device), 12 device country (written by server sensors of the kind Device country), 13 rate limiting (written by the server when it blocks a device, or records in observe mode that it would; see A.4.1b), 16 external (reported by another system, see X.9.20; a report for a tenant has no device and is not listed by GET /v1/events). Events of server sensors carry the id of the sensor that wrote them in sensorId. Address blocks of rate limiting name no device and are not returned by the API, and the event.created webhook does not deliver them.

Every event carries date, the time the server received it, and occurredAt (agent 3.3.0.6 or later), the time it was created on the device as reported by the agent, as UTC ISO 8601. occurredAt is null for events of older agents, for events the server wrote itself and when the reported time lies more than 30 days before or more than 5 minutes after the receipt. date keeps its meaning in /v1/events, /v1/events/{id}, /v1/devices/{id}/events, in ?fields= and in the webhooks; sorting, retention and notifications follow date.

X.9.10 Patch jobs and scheduled patch runs

The API reads both kinds of entries of the Patch history tab (see Chapter 7.5). All routes need the scope patch:read. An entry whose device is outside the tenants or locations of the token answers 404.

Patch jobs. GET /v1/patch-jobs, GET /v1/patch-jobs/{id} and GET /v1/patch-jobs/{id}/items return the jobs an operator started by hand (Patch Now and uninstall) with their items. The list filters with ?deviceId=, ?status= and ?action=. Scheduled runs are not part of it. The status of an item is pending, installing, uninstalling, success (installed, or removed on an uninstall job), restartpending (installed by Windows Update, takes effect after the next restart; from agent 3.3.0.11), failed, skipped or notuninstallable. Once a job with items has finished, its counts follow the items: installedCount counts success and restartpending (on an uninstall job only success), failedCount the failed items and totalItems all items.

Scheduled patch runs. The runs an agent started on its own from the patch schedule of its policy. Agents 3.3.0.5 and newer report them.

  • GET /v1/patch-runs lists them newest first, paginated with ?page= and ?pageSize= (default 50, at most 500). The answer carries items, page, pageSize, total, totalPages and hasMore.
  • Filters: ?deviceId=, ?kind=, ?outcome=, and ?from= and ?to= as RFC 3339 timestamps with an offset, compared against runAt. A timestamp without an offset answers 400.
  • GET /v1/patch-runs/{id} returns one run. id is the numeric run id used by all /patch-runs routes.
  • GET /v1/patch-runs/{id}/items returns { "runId": <id>, "items": [...] } with every update the run looked at. A skipped run has no items.

A run carries:

FieldMeaning
idThe numeric run id.
agentRunIdThe GUID the agent generated for the run.
deviceId, deviceNameThe device.
kindrun when the run reached the installation, skip when no run started.
outcomeFor run: ran, nothing_pending or reboot_pending. For skip: disk_space, informational, disabled, no_settings or window_invalid.
noteThe agent's note on the run, in English.
runAt, finishedAtStart and end of the run in UTC.
runAtLocalThe start on the device's own clock, as text.
inWindow, catchUpWhether the run started inside the maintenance window, or as a catch-up of a missed one.
windowStart, windowEndThe maintenance window of the policy in device time (HH:mm).
installedCount, failedCount, heldBackCount, itemCountThe counts of the run.
rebootRequiredThe run left a restart outstanding.
appStageSkippedWinget and Chocolatey were not checked because Windows updates wait for a restart.
itemsTruncatedThe agent reported only part of the updates; failed updates come first.
durationSeconds, agentVersion, receivedAtDuration, agent version and the time the server received the run.

An item carries id, updateId, updateSource (OS-Mandatory, Winget, Chocolatey, Apt, Dnf, Yum or MacOS), name, status, reason and detail. status is installed, failed, restart_pending, held_back or skipped. reason is the code behind the reason column of the console, for example not_approved, severity_filter, type_filter, ring_until, retry_wait, user_input, deferred, framework_package, no_upgrade, not_outdated, replaced, kept_back, held or unresolvable. detail holds the error text, including the Windows Update error code, or for ring_until and retry_wait the UTC time the update becomes due.

Runs are deleted by the retention of the Patch history (90 days by default).

X.9.11 Tenants of a token and provisioning

Which tenants a token has. Settings → API tokens offers two ways to set the tenants of a token. The switch All tenants of the account sits in the dialog of the token (Add in the toolbar, or the edit icon of an existing token), directly above the tenant selection; it is available from version 3.3.0.10 on.

  • With the switch All tenants of the account off, the token uses the tenants selected in its dialog and, in addition, every tenant it created itself through POST /v1/tenants. Tenants the account gets later are not included.
  • With the switch on, the token uses every tenant its account is assigned to, including tenants assigned or created later. The selection in the dialog is then not an input. An account with Access to all tenants (Chapter 14.5) has every tenant, including tenants created later, so such a token reaches them as well; GET /v1/me reports accountAllTenants: true for it, and the token list shows Currently: All tenants for the token.

In both cases the account is the upper limit: a tenant that is taken from the account is gone for its tokens as well, and a tenant that no longer exists is not part of any token. Changes made in the console reach the API within five seconds.

GET /v1/me shows the result: tenantIds are the tenants the token can use right now, tenantScope is account with the switch on and selected otherwise, and createdTenantIds lists the tenants among tenantIds that the token created itself.

Tenants a token created. POST /v1/tenants assigns the new tenant to the account the token is bound to and records the token with the tenant. The same token can use the tenant from its next request on. Tenants created before version 3.3.0.10 are used by a token only when it is selected for it or when the token uses all tenants of its account.

  • The edit dialog of the token marks these tenants as created by this token and preselects them. Deselecting one and saving withdraws the access; selecting it again grants it like any other tenant of the account.
  • Rotating a token keeps the access, because the token stays the same entry. A newly issued token does not inherit it; select the tenants for the new token.
  • Other tokens of the same account do not get the tenant automatically. They see it when it is selected for them or when they use all tenants of the account.
  • Webhook subscriptions, notification targets and reports that copy the token's tenants when they are created keep that list; they do not grow with the token.
  • A token that is narrowed to locations stays narrowed: it does not see a location it creates in a new tenant.

Provisioning with one token. A tenant, its locations and groups can be created and existing devices moved into them by the same token, one request after the other:

  1. POST /v1/tenants with { "name": "..." } returns the id of the tenant.
  2. POST /v1/locations with { "tenantId": <id>, "name": "..." }.
  3. POST /v1/groups with { "tenantId": <id>, "locationId": <id>, "name": "..." }.
  4. POST /v1/devices/bulk/move with { "ids": [...], "locationId": <id>, "groupId": <id> }; "tenantId": <id> may be sent as well as a cross-check that the location belongs to the new tenant, see X.9.12.

The token needs the scopes organization:write and devices:write, and organization:read and devices:read to read back what it wrote. The bound account needs tenants_enabled, tenants_manage, tenants_add, tenants_locations_add, tenants_groups_add, devices_general and devices_move. The tenant the devices come from has to be one of the token's tenants as well: the device and the target of a move both have to be inside the token's scope. For an automation, bind the token to an account of its own that holds only these permissions and tenants.

X.9.12 Device lists: filters, sorting and moves

Text filters. GET /v1/devices filters by deviceName, label, operatingSystem, domain, lastActiveUser, ipAddressInternal, serialNumber and agentVersion:

  • A value without a wildcard has to match the whole field. Case and accents are ignored.
  • * stands for any number of characters and ? for exactly one: deviceName=web-* (starts with), deviceName=*-prod (ends with), deviceName=*web* (contains), deviceName=web-???? (four characters after the prefix).
  • \*, \? and \\ stand for the character itself. % and _ have no special meaning.
  • A value may be at most 255 characters long and contain at most four *; anything else answers 400 invalid_parameter and names the parameter.

All filters combine with AND, also with the existing ones. platform, deviceClass and geoCountryCode are compared exactly and take no wildcards. search looks for its text anywhere in deviceName, label, serialNumber or ipAddressInternal and takes no wildcards either.

Changed devices. updatedSince (RFC 3339) lists the devices whose name, label, tenant, location, group, platform, device class, authorization, block, operating system, domain, architecture, internal IP address, hardware fields, serial number, manufacturer or model changed at or after that time. The server compares these fields every two minutes. A check-in, the load figures, the external IP address and the agent version do not count as a change. A new device is reported as changed once.

GET /v1/mobile-devices has the text filters deviceName and label. GET /v1/tenants, GET /v1/locations and GET /v1/groups have the text filter name, for example to look a tenant up before creating it.

Sorting. GET /v1/devices sorts by id, deviceName, label, lastAccess, platform, tenantName, locationName, groupName, operatingSystem, serialNumber, agentVersion, cpuUsage, ramUsage and geoCountryCode; a leading - sorts descending, several fields are separated by commas. id follows the order in which the devices were first registered (there is no first-seen timestamp), so sort=-id returns the most recently registered device first. Devices with equal sort values keep a fixed order, so consecutive pages neither repeat nor skip a device.

The highest name with a prefix, without reading the list:

GET /v1/devices?deviceName=web-*&sort=-deviceName&pageSize=1&fields=id,deviceName

total in the answer is the number of devices that match.

Moving devices. PATCH /v1/devices/{id} and POST /v1/devices/bulk/move move a device with locationId, groupId or both. A move needs the permission devices_move on the bound account.

  • locationId moves the device to that location and to the tenant the location belongs to. A location of another tenant therefore moves the device into that tenant. The group of the device is cleared, unless the device is already in that location.
  • groupId moves the device into that group and with it into the group's location and tenant. Sent together with locationId, the group has to belong to that location; otherwise the answer is 400 invalid_parameter.
  • PATCH with "groupId": null takes the device out of its group and leaves the rest as it is.
  • The bulk form accepts tenantId as well. It is optional and has to be the tenant of the target location. tenantId alone answers 400 invalid_parameter, because a device always belongs to a location: send locationId (a location of that tenant) and optionally groupId.
  • The device and the target both have to be inside the token's scope. A target outside it answers 400 invalid_parameter, a device outside it 404 (in the bulk form: not_found for that item).
  • A target in a tenant that is being deleted answers 409 conflict. An id that is not an integer answers 400 invalid_parameter.

The agent keeps its assignment after a move.

X.9.13 Patch compliance

GET /v1/patch-compliance (scope patch:read) returns the compliance figures of the patch management overview (see Chapter 7.4) for the devices inside the tenants and locations of the token:

FieldMeaning
asOfThe instant the figures were computed (RFC 3339, UTC).
scopeThe compliance scope of Patch Management → Settings the figures were counted with: sources, types, severities (the bucket keys critical, high, medium, low, unspecified), approval (approved or approved_and_pending) and graceDays.
devicesTotalAuthorized devices that reported an update inventory in which every operating system source answered, with or without entries in the update catalog. A Linux or macOS device without pending updates is counted (as compliant); a device that has never reported, or a Linux device with a package manager NetLock does not patch (zypper, pacman), is not counted.
devicesCompliantDevices with no scored update outstanding. A device whose open updates all lie outside the scope is compliant.
devicesSecurityCompliantDevices with no security-relevant scored update outstanding (Security classification, Critical, High or Important severity, or a CVE).
compliancePct, securityCompliancePctThe two groups as a percentage of devicesTotal, one decimal; 0 when no device is counted. securityCompliancePct is the headline figure of the overview.
devicesMissingCritical, devicesMissingSecurityDevices with a scored update of severity Critical, or a security-relevant scored update, still outstanding.
overdueSecurity, overdueCriticalOutstanding device-update pairs past their SLA deadline that are security-relevant, or rated Critical.

The figures are counted by the same statements the overview runs, so they match the page for an account with the same tenants. The scope is instance-wide and is changed on the Settings tab (7.6); the API does not change it.

GET /v1/devices/{id}/updates and GET /v1/updates carry inComplianceScope per row: true when the update counts toward compliance under the saved scope, false for an update the console marks as Not scored (for example a driver update, an update of a source outside the scope, a pending update while only approved updates are scored, or an update still inside the grace period).

X.9.14 Device hardware fields

GET /v1/devices and GET /v1/devices/{id} (scope devices:read) return three fields from the device's last inventory upload:

FieldMeaning
macAddressThe MAC of the network adapter that carries ipAddressInternal (the same adapter Wake on LAN uses), upper case and colon separated, e.g. AA:BB:CC:DD:EE:FF. null when no adapter carries that address, when the device has not uploaded an inventory, or when the adapter reports no valid MAC. A device with several active adapters exposes only this one here; every adapter is listed by GET /v1/devices/{id}/inventory/network-adapters (devices:inventory:read).
cpuCoresPhysical cores, the total of all processor packages.
cpuLogicalProcessorsLogical processors (threads), the total of all processor packages.
  • The fields honour ?fields=; ?fields=id,macAddress reads only what it needs. They cannot be sorted or filtered.
  • On multi-socket Windows and Linux machines, the counts cover all processor packages with agent 3.3.0.11 or later.
  • manufacturer and model are reported by Windows, Linux and macOS agents 3.3.0.11 and later (Windows: Win32_ComputerSystem; Linux: the DMI vendor and product name; macOS: Apple and Model Name (Model Identifier), e.g. MacBook Pro (MacBookPro18,3)). An older desktop agent leaves them null.
  • Text values the device did not report are null: operatingSystem, domain, architecture, ipAddressInternal, ipAddressExternal, antivirusSolution, firewallStatus, cpu, ram, gpu, mainboard, tpm, serialNumber, manufacturer, model, lastActiveUser, lastBoot and timezone. label and notes are entered by people and keep an empty string.

Example (abridged):

{
  "id": 139,
  "deviceName": "LAPTOP-0815",
  "ipAddressInternal": "192.168.10.24",
  "macAddress": "3C:52:82:4F:1A:7E",
  "antivirusSolution": "Microsoft Defender Antivirus",
  "cpu": "Intel(R) Core(TM) Ultra 7 155U",
  "cpuUsage": 12,
  "cpuCores": 12,
  "cpuLogicalProcessors": 14,
  "manufacturer": "LENOVO",
  "model": "21KX0012GE",
  "tpm": "True"
}

X.9.15 Agent packages

An agent package configuration is what an agent installer enrols with: tenant, location, server addresses, language, installer texts and forward proxy. Its package guid is part of the installer's download address; treat it like a password.

ScopeCalls
agents:readGET /v1/agent-packages, GET /v1/agent-packages/{id}
agents:writePOST /v1/agent-packages, PATCH /v1/agent-packages/{id}, DELETE /v1/agent-packages/{id}
agents:installer-url:readGET /v1/agent-packages/{id}/installer-url. Sensitive: the link enrols any machine it runs on. Every retrieval is audited and the call has its own rate limit.

The writing calls need the account permission agent_installers_enabled. A package outside the token's tenants (or, for a token restricted to locations, outside its locations) answers 404.

Create. POST /v1/agent-packages with { name, tenantId, locationId?, ssl?, communicationServers?, remoteServers?, updateServers?, trustServers?, fileServers?, language?, autoAuthorizeUntil?, installer texts, proxy fields }:

  • tenantId is required and has to be inside the token's scope. locationId has to name a location of that tenant, otherwise 400 invalid_parameter. A token restricted to locations has to name one of its own locations; without locationId or with another location it answers 403 location_restricted.
  • Defaults: the instance's own server addresses, language en-US, ssl true, the standard installer texts, proxyMode auto.
  • Answers 201 { id, created, installerUrlNote }. The guid is never returned. A name that already exists answers 409 duplicate_name.
  • A package created through the API is always unmanaged. Managed packages (one per tenant and location) are created by the console.

Change. PATCH /v1/agent-packages/{id} uses merge-patch: a field left out stays as it is. tenantId cannot be changed. locationId is checked as for create. Naming any proxy field rewrites the whole proxy block. A managed package answers 409 managed_package.

Delete. DELETE /v1/agent-packages/{id} removes the configuration, its package guid history and its installer build state. On an instance with the file server role it also removes the stored installer files; elsewhere the files stay on disk, but their download address answers 410 because the guid is gone. Answers 204.

  • 409 package_in_use while devices still authenticate with the current guid or a guid that has not been revoked. Their agents would no longer be able to connect. The detail names the number of devices. Move or uninstall those devices first. A device with a queued uninstall counts until it has been removed.
  • 409 managed_package for a managed package while its location exists, because the console would create it again. Once the location has been deleted, the managed package can be deleted here.

Installer link. GET /v1/agent-packages/{id}/installer-url?architecture=<win-x64|win-arm64|linux-x64|linux-arm64|osx-x64|osx-arm64> returns the download URL of a built installer with its sha512. An installer that is not built yet answers 409 with its build status. Installers are prebuilt only for the managed packages the console keeps per tenant and location. An unmanaged package, which includes every package created through the API, has no prebuilt installer and answers 409 installer_not_available; download its installer from the console's agent download dialog instead.

X.9.16 Report templates and SQL access

Custom SQL in report templates runs only as the MySQL user configured under Settings → SQL access (see Set up SQL access). Statements that match the ones shipped with the release (built-in templates and unchanged copies of them) run without it.

CodeStatusCallsMeaning
sql_access_not_configured403POST /v1/report-templates, PATCH /v1/report-templates/{id}, POST /v1/reports/generate, POST /v1/report-schedules, PATCH /v1/report-schedules/{id}The template (sent, or referenced by the generation or the schedule) contains custom SQL and SQL access is not configured or the configured user is refused. Always the case on cloud instances.
sql_invalid422POST /v1/report-templates, PATCH /v1/report-templates/{id}MySQL refused a statement when it was checked with EXPLAIN as the SQL access user. The detail carries MySQL's message and the name of the widget.

An edit share applies to that one template.

POST /v1/report-templates and PATCH /v1/report-templates/{id} answer with warnings: widgets whose SQL does not filter by tenant, or names @tenant_id in a form that is not replaced, and templates that describe the whole instance. They are notes only; nothing is refused because of them.

Reports per tenant

CallFieldMeaning
POST /v1/reports/generatetenantIds, perTenantWithout tenantIds, a token that reaches every tenant reports over all tenants (allTenants: true in the answer); any other token reports for its own tenants. perTenant: true makes one report per tenant (at most 25) and answers 202 with reports: [{ id, tenantId }]; the request counts once against the report rate limit. templateId names a stored template; the built-in templates have no id, generate a copy of one.
GET /v1/reports, GET /v1/reports/{id}tenantIds, filter tenantIdtenantIds is the list of tenants a report covers, null for all tenants. tenantId matches reports whose list contains the tenant and reports over all tenants. The download is named <template>_<tenant>_<date>_<time>.<extension> for a report made for one tenant.
POST/PATCH /v1/report-schedulestenantIds, perTenant, sendToTenantContacts, exportFormatA new schedule without tenantIds covers all tenants, including tenants created later, for a token that reaches every tenant (tenantIds: null in the answer), otherwise the token's tenants; tenantIds: null asks for all tenants explicitly, an empty list is refused. PATCH keeps the stored tenants and the webhook delivery when they are not sent. exportFormat accepts JSON. sendToTenantContacts sends each report made for one tenant to the report contacts of that tenant.

A report for selected tenants leaves out widgets whose SQL does not filter by tenant (Chapter 11.10); a template that describes the whole instance answers 422 for anything but all tenants combined.

Tokens with some tenants. A token that does not reach every tenant lists only generated reports and schedules whose tenants are all its own; reading, downloading, changing or deleting any other one answers 404. A token restricted to locations answers 403 location_restricted for POST /v1/reports/generate and for creating or changing a schedule, because a report covers whole tenants.

X.9.17 Device Control learning

The learning period of a device (see Chapter 6.8) can be read and controlled per device, the same way as on the device's USB Devices tab.

CallScopePermission
GET /v1/devices/{id}/device-control/learningdevices:read—
POST /v1/devices/{id}/device-control/learning/relearndevices:usb-learning:writedevices_usb_learning
POST /v1/devices/{id}/device-control/learning/enddevices:usb-learning:writedevices_usb_learning
  • The answer of all three calls is { deviceId, status, policyId, policyName, source, startedAt, learningUntil, initialScanOnly, requestedBy, requestedAt }, with times in UTC. status is none, pending (a re-learn was requested and starts at the device's next policy sync), learning, done or migrated (learned under the policy-wide auto-whitelist of a release before 3.3.0.11).
  • relearn stores the request and asks a connected device to sync right away. It answers 422 unsupported_platform for a device that is not a Windows computer and 422 device_control_off when the device's policy has Device Control off or the device has no policy.
  • end ends a running or requested period at once and answers 409 not_learning when none runs.
  • devices:usb-learning:write is a dangerous scope: while a learning period runs, every device connected to the device is whitelisted for it. Existing tokens do not get the scope; it has to be added to a token explicitly.
  • A device outside the token's tenants answers 404. Every re-learn and end is written to the audit log.
  • The learning period is set with auto_whitelist and auto_whitelist_duration_minutes (0 = devices connected when learning starts, up to 20160) in a policy's Device Control settings; auto_whitelist_until is ignored.
  • GET /v1/device-control/whitelist (scope devicecontrol:read) marks the entries a device learned with autoLearned: true. Their author is Auto-Whitelist (Agent: <device name>) with the device's current name; for an entry whose device was deleted it keeps the name the device had when the entry was learned. Entries created in the web console or over the API have autoLearned: false and the account as author.

X.9.18 Ticket comments: plain text and HTML

POST /v1/tickets/{id}/comments, POST /v1/tickets/{id}/close and POST /v1/tickets/{id}/reopen take an optional format next to comment. A comment made through the API is always an internal note.

POST /v1/tickets/42/comments
{ "comment": "<div><b>Incident</b> opened</div>", "format": "html" }

201
{ "id": 981, "ticketId": 42, "isInternal": true, "format": "html", "created": true }
  • format is text or html; any other value answers 400 invalid_parameter. On close and reopen it is ignored when no comment is sent. The 201 of /comments reports the resolved format.
  • Without format (or with null) the format is detected from the content. It is html when the comment starts with <!DOCTYPE html, contains a <br>, <hr> or <img …> tag, or contains a known HTML element with its closing tag: html, head, body, style, div, p, span, table, tbody, thead, tr, td, th, ul, ol, li, h1–h6, b, strong, i, em, u, a, pre, code, blockquote, font, center. Everything else stays text, for example List<string>, a < b, <hostname>, <# … #> or <Configuration>…</Configuration>.
  • For text that contains such tags, or HTML built from other elements, send format.
  • text is shown as written, with its line breaks. In GET /v1/tickets/{id}/comments, body holds the comment and bodyHtml is empty.
  • html is stored as delivered and returned in bodyHtml. body holds the text derived from it, without <style>, <script> and <head> content. It is empty when the HTML holds no text, for example only an embedded image; the note is still accepted.
  • The console cleans HTML when it shows it: style blocks and scripts are removed, external images do not load, links to web addresses are not clickable, and only a safe set of inline styles remains. An e-mail template therefore shows its content, but not the design of its stylesheet.
  • POST /v1/tickets is not affected: description stays plain text.

X.9.19 Alerts

Events report what happened; an alert says what is wrong right now. GET /v1/alerts folds the events of one problem into one entry with a state. It needs the scope alerts:read.

An alert is the event that opened it: its id is the id of that event. Repetitions raise occurrences and lastSeenAt; severity is the highest severity the alert reached.

SourceOpens withCloses withresolvedBy
sensora sensor event or an execution error of a sensor, severity above lowthe notice Sensor Resolved of that sensor, when the sensor has Notify when resolved switched on; otherwise reading or hiding the eventauto, read, hidden
uptimeDevice disconnected.Device connected.auto
websiteWebsite unreachable.Website recovered.auto
externala report with state opena report with state resolvedapi
antivirus, port_scanner, patch, authorization, country, endpoint_protection, security_incidentevery event above severity low; each event is an alert of its ownreading or hiding the eventread, hidden

Other website events (performance, certificates, content), jobs, SNMP discovery, remote shell results and rate limiting open no alert.

Sensors. The agent sends a resolved notice only for a sensor with that setting, and only after a trigger. A sensor without the setting, an event of an older agent without a sensor id and an execution error alone have nothing to wait for, so their alert ends like a one-shot alert. Repetitions still fold into that one alert.

Difference from the dashboard. The sensor status on the dashboard counts a sensor as acknowledged once its event is read or hidden. The alert of a sensor that sends a resolved notice stays open until that notice arrives, because reading an event does not fix the cause.

Upper limit. Every open alert, of any source, is resolved with resolvedBy expired when no new event arrived for 30 days (Settings → Retention). A problem that keeps producing events stays open; a device that stays offline writes no further events and its alert ends after that time. An open alert is resolved with resolvedBy auto when its device or tenant is removed, and a sensor, uptime or external alert also when its device loses the authorization.

Moved devices. An alert follows its device. When a device moves to another tenant, the open alert with all its events belongs to the new tenant, usually within a minute and at once with the next event. The old tenant can no longer read it.

Feed. The list runs oldest change first. Page with limit and cursor, then keep the last nextCursor and ask again later: it is also returned on the last page, and every change to an alert moves the alert behind it. updatedSince (RFC 3339) sets the start of a feed and is ignored when a cursor is given.

GET /v1/alerts?updatedSince=2026-11-01T00:00:00Z&minSeverity=high&limit=100
GET /v1/alerts?cursor=<nextCursor>

Filters: state (open, resolved), tenantId, deviceId, source (comma separated), minSeverity (low, moderate, high, critical). GET /v1/alerts/{id} returns one alert, GET /v1/alerts/{id}/events the opening event, the repetitions and the all-clear.

A change shows up within about 15 seconds. An alert belongs to the tenant of its device, or to the tenant named on the event when it has no device. A token limited to locations sees only alerts of devices in those locations.

Retention. The cleanup keeps the opening event of an open alert, and of a resolved alert an integration still follows. Later events of an alert age normally; GET /v1/alerts/{id}/events then lists what is left.

X.9.20 Reporting alerts of other systems

POST /v1/alerts/ingest with the scope alerts:ingest writes an event of type 16. The console lists it, and the notification targets receive it like any other event.

{
  "source": "backup",
  "dedupKey": "plan-7",
  "deviceId": 12,
  "severity": "high",
  "title": "Backup failed",
  "description": "Plan 7 ended with an error."
}
  • source: 1 to 32 lower case letters, digits, - and _. It becomes reportedBy of the event.
  • dedupKey: identifies the alert of a device, or of a tenant when no device is named, inside the source, up to 140 characters. Surrounding spaces are removed; upper and lower case are different keys.
  • deviceId or tenantId. A token limited to locations has to name a device.
  • severity and title are required for state open.
  • state: open (default) or resolved.

Reports for the same device, or for the same tenant without a device, with the same source and dedupKey fold into one alert until a report with state resolved closes it. A later report opens a new alert. A report that repeats an open alert does not notify again. An alert nobody closes ends with the upper limit in X.9.19. The answer is 202 with eventId, key and state; the alert exists a few seconds later. Idempotency-Key is honoured.

X.9.21 External references

A tenant, location or device can carry its id in other systems, one per system. A connector or a script stores it to find the object again.

RouteScope
GET /v1/{tenants|locations|devices}/{id}/external-refsexternal-refs:read
GET /v1/{tenants|locations|devices}/{id}/external-refs/{system}external-refs:read
PUT /v1/{tenants|locations|devices}/{id}/external-refs/{system}external-refs:write
DELETE /v1/{tenants|locations|devices}/{id}/external-refs/{system}external-refs:write
GET /v1/external-refs?system=&externalId=external-refs:read

system is a lower case name of up to 64 letters, digits, dots, - and _. The body of PUT holds externalId (up to 191 characters) and optionally externalName. A token limited to locations can read the references of its tenants but not change them (403 location_restricted), because such a reference applies to all locations. External ids compare exactly, including case. The search returns at most 200 objects, only inside the token's scope. Removing a device or a tenant removes its references. external-refs:read requires tenants_enabled, external-refs:write additionally settings_integrations_manage.

X.9.22 Device usage per tenant

GET /v1/tenants/{id}/usage and GET /v1/usage/tenants (all tenants of the token) with the scope usage:read count the devices of a tenant over a period. The server records every device once a day, shortly after midnight on the clock of the instance; history starts on the day the instance was updated to 3.3.0.11. usage:read requires tenants_enabled and devices_general.

ParameterMeaningDefault
from, toPeriod, yyyy-MM-dd, inclusive, at most 400 daysCurrent month up to yesterday
aggregatemax, avg or last: which number value returnsmax
authorizedOnlyOnly devices that were authorized on that daytrue
excludeBlockedLeave out devices that were blocked on that daytrue
onlineInPeriodOnly devices that were seen on at least one day of the periodtrue
platformwindows, linux, macos, android, ios, comma separatedall
deviceClasscomputer, mobile, comma separatedall

A day counts the devices of that day that match. max, avg (rounded, .5 upwards) and last are computed over the days of the period for which a record exists; a day with a record and no matching device counts as zero. The answer holds value, max, avg, last, the number of days, and current, the same rules applied to the devices as they are now. GET /v1/tenants/{id}/usage also lists daily.

A device that checks in shortly after midnight, before the record is written, counts as seen on the day before. A day on which no server ran has no record. days says how many days of the period have a snapshot, tenantDays on how many of them the tenant had any device, whatever the rules and filters. tenantDays 0 means that the period says nothing about the tenant, which is not the same as a count of 0.

X.9.23 Webhook events

Subscriptions (/v1/webhooks) know these event types. A subscription without a list of events receives all of them, also types added later.

Every delivery is signed; X.10 shows how a receiver verifies it, with examples in C#, Python and Node.js. Subscriptions can also be managed in the web console under Settings → Integrations → Signed webhooks.

TypeSent whendata
event.createdA row was added to the eventsThe event with sensorId, alertId and consoleUrl
device.registeredA device appearedThe device
device.updatedA field listed in X.9.12 under updatedSince changedThe device with updatedAt and consoleUrl
device.deletedA device was removedid, tenantId, deviceName, deletedAt
alert.openedAn alert was openedThe alert as in GET /v1/alerts/{id}
alert.updatedAn open alert fired againThe alert
alert.resolvedAn alert was resolvedThe alert

A subscription made with a token limited to locations keeps that limit (locationIds) and receives only what happened in those locations, by the location the device has at delivery time. Events and alerts without a device and device.deleted have no location and are not delivered to it. A token limited to locations sees and changes only subscriptions inside its locations.

A new subscription starts at the present. Several changes between two runs of the feed arrive as one alert.updated; alert.opened always comes before the other events of an alert. A subscription also gets alert.opened for an open alert whose device moved into its tenants. event.created waits up to two minutes for the alert state so that alertId is set. consoleUrl is the link to the device in the console and is null without a public console URL. A new device can additionally produce one device.updated.

X.9.24 Managed tokens of integrations

A connection of the integrations store reads NetLock through this API with a token of its own. Such a managed token is an ordinary row in the token list with the chip Integration: <name>, and these differences:

  • It is valid only on the local listener of the server (Integrations:Loopback_Port, by default 127.0.0.1:7480). The public port answers it like an unknown token, with 401.
  • It cannot be edited, rotated or revoked in the token list. It belongs to its connection: NetLock replaces it every 30 days and when the account of the connection changes, and revokes it when the connection is disconnected or deleted.
  • Its secret is stored encrypted for the server and is shown to nobody.
  • Its tenants are the mapped tenants of the connection, within the tenants of the account it is bound to. Its rights are its scopes and the live permissions of that account, as for any token.
  • It does not count against the token limit of the instance, and it has its own limit of 3000 requests per minute.

All its calls appear in the API request log like those of any other token.

X.9.25 App Hub file applications

An App Hub application of the source file runs a file of the file server (see Deploy an installer file from the file server).

Create and change (POST / PATCH /v1/app-hub/apps, scope apphub:write):

FieldMeaning
sourceTypefile
fileIdId of a file on the file server (GET /v1/files). Required on create. Needs the scope files:read and the permission file_server_enabled in addition (otherwise 403 insufficient_scope / 403 insufficient_permission); a file outside the token's reach answers 404.
fileInstallArgs, fileUpdateArgs, fileUninstallArgsArguments of the actions, up to 2048 characters each, without control characters, passed to the program without a shell. An empty fileUpdateArgs means the install arguments.
fileUninstallModenone (default), file (the same file with fileUninstallArgs; .msi, .exe, .ps1, .sh) or script (uninstallScript).
  • Guid, name and SHA-512 are read from the files row when the application is saved. Devices run the file only while it is unchanged; otherwise fileState shows changed.
  • targetOs follows the file type and scriptShell the target system; leave both out (another targetOs or a scriptShell answers 400). The application always runs elevated (requiresElevation: false answers 400) and has no install or update script.
  • version and detectionScript are required.
  • 400 invalid_parameter also for: a file collected from a device or below devices/, a file in the netlock folder (404 without file_server_netlock), an unsupported type, a file without a valid SHA-512, an uninstall mode the type does not offer, script without uninstallScript, file fields on an application of another source.
  • PATCH: fileId picks a (new) file and pins its current SHA-512; without fileId the stored file and hash are kept. Changing the arguments or the uninstall mode needs file_server_enabled as well. Changing the application to another source clears its file fields. Pending deployments that have not started on any device take the new definition with the call (refreshedDeployments).
  • fileSha512 does not cover files the arguments load in addition (TRANSFORMS=, PATCH=, more package operands); keep them on a trusted share.

Read (GET /v1/app-hub/apps, GET /v1/app-hub/apps/{id}): a file application carries fileId (the files row its guid names, null when that row is gone), fileName (the name when the file was chosen), fileSha512 (the pinned hash), fileInstallArgs, fileUpdateArgs, fileUninstallArgs, fileUninstallMode and fileState: ok, missing (no files row has the guid) or changed (the row holds other bytes than the application pins; devices refuse to run it). fileState is null for other sources.

Software deployments (POST / PATCH /v1/software-deployments): an item with the appHubAppId of a file application copies the file's guid, its pinned SHA-512 and the arguments of the item's action from the application. An uninstall item needs an uninstall mode other than none; a file whose fileState is missing or changed is refused with 400. An item with sourceType: file always needs appHubAppId. GET /v1/software-deployments/{id}/items returns fileId, fileSha512 and fileArgs for file items.

Lock conflicts. A write of an App Hub application or a software deployment that collides with another write at the same moment saves nothing and answers 503 temporarily_unavailable with Retry-After: 5. Send the request again after that time.

Files in use. POST /v1/files over the name of a file and DELETE /v1/files/{id} answer 409 file_in_use when an App Hub file application or an open software deployment (draft, pending or running) uses the file. The problem document lists appIds and deploymentIds. Renaming and moving (PATCH /v1/files/{id}) stay allowed and keep the guid.