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:readordevices: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 accountthey 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 answers404. See X.9.11. - A rate limit in requests per minute (default 600). Requests above it answer
429with aRetry-Afterheader. 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" }
]
}sourcenames who wrote the device value last:manual(console),script(write-back from a script) orapi.isSecretistruefor aSecretfield; itsvalueis alwaysnull.- 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 }
]
}levelnames where the value comes from:device,group,location,tenant,global, ornonewhen no level holds a value.sourceis set only whenlevelisdevice.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:
| Level | Routes | Visible when |
|---|---|---|
| Global | GET, PUT /v1/custom-fields/global | Always; needs settings_custom_fields_enabled |
| Tenant | GET, PUT /v1/tenants/{id}/custom-fields | The tenant is in the token's tenant scope |
| Location | GET, PUT /v1/locations/{id}/custom-fields | The location is in the token's tenant scope and, when the token is limited to locations, in that list |
| Group | GET, PUT /v1/groups/{id}/custom-fields | As 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
Manualfields of typeText,MultilineorSecretare accepted, and a value may not exceed 64 KB. Any other entry answers400 invalid_parameterwith the reason, and nothing of the request is written. nullclears 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. updatedByis 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"
}conditionsis the rule's condition list as stored. Every entry hastypeandnegate; an entity condition carries its id (deviceId,tenantId,locationIdorgroupId) and the entity'sname;internal_ipanddomaincarryvalue;platformcarriesvalues;device_attributecarriesfield,opandvalue.- A
locationorgroupcondition additionally carrieslocationIds/groupIdsandnamesin the same order (nullfor an entity that is gone or outside the token's tenants). It may name several entities ("is one of"); thenlocationId/groupIdandnamearenulland 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. policyNameisnullfor a rule that assigns no policy.sensorIdsandjobIdsare the sensors and jobs the rule adds to every matching device on top of its policy.deviceId,tenantId,locationIdandgroupIdon 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 intenantId;effectiveTenantIdis the tenant the rule belongs to, ornullfor 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 }
]
}-
conditionsneeds at least one entry; all have to hold. Each entry may carrynegate: 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[] }withWindows,Linux,MacOS,Android,iOS.device_attribute { field, op, value }withfieldone ofdevice_name,operating_system,label,serial_number,device_class,architecture,manufacturer,model,mainboard,cpu,gpu,agent_version,last_active_user,timezone,antivirus_solutionandopone ofeq,contains,starts_with,wildcard,regex.service { field, op, value, status }withfieldnameordisplay_name,opeq,containsorwildcardandstatusany,runningorstopped(a Linux unit matches with or without.service).application { op, value, versionOp?, version? }withversionOpeq,gte,ltorstarts_with.custom_field { key, op, value? }withkeythe field key of a custom field definition andopeq,contains,regexoris_empty.
A
locationorgroupcondition may sendlocationIds[]/groupIds[](up to 500) instead oflocationId/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 answers400, and so dodeviceIdsandtenantIds. A list with one id is stored as the single id. Every id has to be inside the token's tenant scope (otherwise404); all ids of one condition have to belong to the same tenant and lie inside the tenant or location the rule names elsewhere (otherwise400).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_parameterwith 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}/assignthe route names it),sensorIdsorjobIds; a body with none of them answers400.sensorIdsandjobIdsare lists of existing ids; an unknown id, or a sensor the SNMP discovery manages, answers400 invalid_parameternaming 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.enableddefaults totrue.prioritydefaults 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. -
PATCHhas merge-patch semantics onname,description,policyName,enabled,priority,conditions,sensorIdsandjobIds: a field left out stays as it is;conditions,sensorIdsandjobIdseach replace their whole list ([]empties it).policyName: nullremoves 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 answers201; send anIdempotency-Keyheader 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/jobsand/v1/sensors, the single reads andGET /v1/devices/{id}/sensorsreturnlabel; it honours?fields=.- The lists filter with
?label=(exact, case-insensitive), and?search=also matches the label. Scripts and jobs sort withsort=label. POST /v1/scripts,/v1/jobsand/v1/sensorsacceptlabel. OnPATCH, a body withoutlabelleaves it unchanged;""ornullremoves it. A longer value or a value that is not a string answers400 invalid_parameter.- The label is not part of the document the agents receive: a
PATCHthat 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/usersandGET /v1/users/{id}(users:read) returnroleas{ "id": 3, "name": "Technician", "builtIn": false }, ornullfor custom permissions, androleOriginwith the name of the role a custom account was detached from (nullwhen it never followed one). The list filters with?role=<name>,?role=customand?roleId=<int>, andsort=rolesorts by the role name. Both fields honour?fields=.GET /v1/rolesandGET /v1/roles/{id}(users:read) list the roles withid,name,description,builtIn,memberCount,createdAtandupdatedAt; the single read also carriespermissions, the same object shape asGET /v1/users/{id}/permissions. The list filters with?builtIn=and?search=.POST /v1/userstakesroleId. WithroleIdthe account starts with that role's permissions and follows it; because that grants permissions, the token needsusers:permissions:writein addition tousers:write, and a role that holds a permission the bound account does not answers409 permission_escalation_forbidden. WithoutroleIdthe account has custom permissions and none of them. The response carriesroleandroleOrigin.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 androleOriginnames the role. An unknownroleIdanswers404; the self-edit and escalation refusals of the permissions write apply.PUT /v1/users/{id}/permissionsdetaches an account that follows a role: the permissions written become its own,roleisnullafterwards androleOriginnames the role.PATCH /v1/users/{id}does not acceptrole. Disabling, deleting or demoting the last enabled account that holdsusers_enabled,users_manageandusers_edit(throughPATCHwithenabled: false,DELETE, the permissions write or a role without those three keys) answers409 last_user_manager.- From 3.3.0.5,
roleis an object ornull;POSTandPATCHreject arolefield 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/usersandGET /v1/users/{id}returnallTenants(the account has access to all tenants, including tenants created later) andtenantsas the effective list of tenant ids: every existing tenant whenallTenantsis true, otherwise the assigned tenants that exist. Both honour?fields=; the list filters with?allTenants=true|false.GET /v1/users/{id}/permissionsreturnstenantsandallTenantsnext topermissions, so a read-then-write round trip carries the whole tenant state.POST /v1/usersacceptsallTenants(defaultfalse, whateverroleIdis). It needsusers:permissions:writelikeroleId, and only a token that itself reaches every tenant may set it: a token that usesAll tenants of the accountwhile that account has access to all tenants. Any other token answers409 permission_escalation_forbidden. The response carriesallTenants.PUT /v1/users/{id}/permissionstakes{ permissions, tenants, allTenants? }.allTenantsleft out leaves the switch as it is, so a client that replays an earlier response does not switch an administrator off;truecarries the same refusal as onPOST;falseis always allowed. While the switch is on,tenantsis stored but not evaluated. The response carriesallTenantsBeforeandallTenants, and the audit entry names the switch when it changed.GET /v1/mereturnsaccountAllTenants: the bound account has access to all tenants, sotenantIdsof a token withAll tenants of the accountis complete.- Update the Web Console before the server. Until then the server evaluates every account from its tenant list alone, and
allTenants: trueonPOSTorPUTanswers409 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}andGET /v1/enrollment/pendingreturngeoCountryCode(ISO 3166-1 alpha-2, upper case) andgeoCountryName(the English name from the database). Both arenullfor 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/devicesfilters with?geoCountryCode=DE(exact, one code) and sorts withsort=geoCountryCodeorsort=-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/sensorsandGET /v1/sensors/{id}return them withserverSensor { allTenants, triggers }; for every other sensorserverSensorisnull. The triggers depend on the sub-category:0Unauthorized device:new_device,reinstall,hwid_changed,license_limit.hwid_changedis the one trigger whose device stays authorized; the server only records the new hardware ID.2Device country:outside_countries,refused,country_changed.
- The tenants a server sensor covers are not returned;
allTenantstells whether it covers every tenant, including tenants created later. - Server sensors are read-only through the API:
POST,PUTandPATCHdo 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-runslists them newest first, paginated with?page=and?pageSize=(default 50, at most 500). The answer carriesitems,page,pageSize,total,totalPagesandhasMore.- Filters:
?deviceId=,?kind=,?outcome=, and?from=and?to=as RFC 3339 timestamps with an offset, compared againstrunAt. A timestamp without an offset answers400. GET /v1/patch-runs/{id}returns one run.idis the numeric run id used by all/patch-runsroutes.GET /v1/patch-runs/{id}/itemsreturns{ "runId": <id>, "items": [...] }with every update the run looked at. A skipped run has no items.
A run carries:
| Field | Meaning |
|---|---|
id | The numeric run id. |
agentRunId | The GUID the agent generated for the run. |
deviceId, deviceName | The device. |
kind | run when the run reached the installation, skip when no run started. |
outcome | For run: ran, nothing_pending or reboot_pending. For skip: disk_space, informational, disabled, no_settings or window_invalid. |
note | The agent's note on the run, in English. |
runAt, finishedAt | Start and end of the run in UTC. |
runAtLocal | The start on the device's own clock, as text. |
inWindow, catchUp | Whether the run started inside the maintenance window, or as a catch-up of a missed one. |
windowStart, windowEnd | The maintenance window of the policy in device time (HH:mm). |
installedCount, failedCount, heldBackCount, itemCount | The counts of the run. |
rebootRequired | The run left a restart outstanding. |
appStageSkipped | Winget and Chocolatey were not checked because Windows updates wait for a restart. |
itemsTruncated | The agent reported only part of the updates; failed updates come first. |
durationSeconds, agentVersion, receivedAt | Duration, 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 accountoff, the token uses the tenants selected in its dialog and, in addition, every tenant it created itself throughPOST /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/mereportsaccountAllTenants: truefor it, and the token list showsCurrently: All tenantsfor 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 tokenand 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:
POST /v1/tenantswith{ "name": "..." }returns theidof the tenant.POST /v1/locationswith{ "tenantId": <id>, "name": "..." }.POST /v1/groupswith{ "tenantId": <id>, "locationId": <id>, "name": "..." }.POST /v1/devices/bulk/movewith{ "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 answers400 invalid_parameterand 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,deviceNametotal 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.
locationIdmoves 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.groupIdmoves the device into that group and with it into the group's location and tenant. Sent together withlocationId, the group has to belong to that location; otherwise the answer is400 invalid_parameter.PATCHwith"groupId": nulltakes the device out of its group and leaves the rest as it is.- The bulk form accepts
tenantIdas well. It is optional and has to be the tenant of the target location.tenantIdalone answers400 invalid_parameter, because a device always belongs to a location: sendlocationId(a location of that tenant) and optionallygroupId. - 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 it404(in the bulk form:not_foundfor that item). - A target in a tenant that is being deleted answers
409 conflict. An id that is not an integer answers400 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:
| Field | Meaning |
|---|---|
asOf | The instant the figures were computed (RFC 3339, UTC). |
scope | The 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. |
devicesTotal | Authorized 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. |
devicesCompliant | Devices with no scored update outstanding. A device whose open updates all lie outside the scope is compliant. |
devicesSecurityCompliant | Devices with no security-relevant scored update outstanding (Security classification, Critical, High or Important severity, or a CVE). |
compliancePct, securityCompliancePct | The two groups as a percentage of devicesTotal, one decimal; 0 when no device is counted. securityCompliancePct is the headline figure of the overview. |
devicesMissingCritical, devicesMissingSecurity | Devices with a scored update of severity Critical, or a security-relevant scored update, still outstanding. |
overdueSecurity, overdueCritical | Outstanding 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:
| Field | Meaning |
|---|---|
macAddress | The 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). |
cpuCores | Physical cores, the total of all processor packages. |
cpuLogicalProcessors | Logical processors (threads), the total of all processor packages. |
- The fields honour
?fields=;?fields=id,macAddressreads 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.
manufacturerandmodelare reported by Windows, Linux and macOS agents 3.3.0.11 and later (Windows:Win32_ComputerSystem; Linux: the DMI vendor and product name; macOS:AppleandModel Name (Model Identifier), e.g.MacBook Pro (MacBookPro18,3)). An older desktop agent leaves themnull.- 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,lastBootandtimezone.labelandnotesare 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.
| Scope | Calls |
|---|---|
agents:read | GET /v1/agent-packages, GET /v1/agent-packages/{id} |
agents:write | POST /v1/agent-packages, PATCH /v1/agent-packages/{id}, DELETE /v1/agent-packages/{id} |
agents:installer-url:read | GET /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 }:
tenantIdis required and has to be inside the token's scope.locationIdhas to name a location of that tenant, otherwise400 invalid_parameter. A token restricted to locations has to name one of its own locations; withoutlocationIdor with another location it answers403 location_restricted.- Defaults: the instance's own server addresses,
languageen-US,ssltrue, the standard installer texts,proxyModeauto. - Answers
201 { id, created, installerUrlNote }. The guid is never returned. A name that already exists answers409 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_usewhile 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_packagefor 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.
| Code | Status | Calls | Meaning |
|---|---|---|---|
sql_access_not_configured | 403 | POST /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_invalid | 422 | POST /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
| Call | Field | Meaning |
|---|---|---|
POST /v1/reports/generate | tenantIds, perTenant | Without 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 tenantId | tenantIds 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-schedules | tenantIds, perTenant, sendToTenantContacts, exportFormat | A 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.
| Call | Scope | Permission |
|---|---|---|
GET /v1/devices/{id}/device-control/learning | devices:read | — |
POST /v1/devices/{id}/device-control/learning/relearn | devices:usb-learning:write | devices_usb_learning |
POST /v1/devices/{id}/device-control/learning/end | devices:usb-learning:write | devices_usb_learning |
- The answer of all three calls is
{ deviceId, status, policyId, policyName, source, startedAt, learningUntil, initialScanOnly, requestedBy, requestedAt }, with times in UTC.statusisnone,pending(a re-learn was requested and starts at the device's next policy sync),learning,doneormigrated(learned under the policy-wide auto-whitelist of a release before 3.3.0.11). relearnstores the request and asks a connected device to sync right away. It answers422 unsupported_platformfor a device that is not a Windows computer and422 device_control_offwhen the device's policy has Device Control off or the device has no policy.endends a running or requested period at once and answers409 not_learningwhen none runs.devices:usb-learning:writeis 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_whitelistandauto_whitelist_duration_minutes(0= devices connected when learning starts, up to20160) in a policy's Device Control settings;auto_whitelist_untilis ignored. GET /v1/device-control/whitelist(scopedevicecontrol:read) marks the entries a device learned withautoLearned: true. TheirauthorisAuto-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 haveautoLearned: falseand the account asauthor.
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 }formatistextorhtml; any other value answers400 invalid_parameter. Oncloseandreopenit is ignored when nocommentis sent. The201of/commentsreports the resolved format.- Without
format(or withnull) the format is detected from the content. It ishtmlwhen 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 staystext, for exampleList<string>,a < b,<hostname>,<# … #>or<Configuration>…</Configuration>. - For text that contains such tags, or HTML built from other elements, send
format. textis shown as written, with its line breaks. InGET /v1/tickets/{id}/comments,bodyholds the comment andbodyHtmlis empty.htmlis stored as delivered and returned inbodyHtml.bodyholds 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/ticketsis not affected:descriptionstays 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.
| Source | Opens with | Closes with | resolvedBy |
|---|---|---|---|
sensor | a sensor event or an execution error of a sensor, severity above low | the notice Sensor Resolved of that sensor, when the sensor has Notify when resolved switched on; otherwise reading or hiding the event | auto, read, hidden |
uptime | Device disconnected. | Device connected. | auto |
website | Website unreachable. | Website recovered. | auto |
external | a report with state open | a report with state resolved | api |
antivirus, port_scanner, patch, authorization, country, endpoint_protection, security_incident | every event above severity low; each event is an alert of its own | reading or hiding the event | read, 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 becomesreportedByof 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.deviceIdortenantId. A token limited to locations has to name a device.severityandtitleare required for stateopen.state:open(default) orresolved.
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.
| Route | Scope |
|---|---|
GET /v1/{tenants|locations|devices}/{id}/external-refs | external-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.
| Parameter | Meaning | Default |
|---|---|---|
from, to | Period, yyyy-MM-dd, inclusive, at most 400 days | Current month up to yesterday |
aggregate | max, avg or last: which number value returns | max |
authorizedOnly | Only devices that were authorized on that day | true |
excludeBlocked | Leave out devices that were blocked on that day | true |
onlineInPeriod | Only devices that were seen on at least one day of the period | true |
platform | windows, linux, macos, android, ios, comma separated | all |
deviceClass | computer, mobile, comma separated | all |
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.
| Type | Sent when | data |
|---|---|---|
event.created | A row was added to the events | The event with sensorId, alertId and consoleUrl |
device.registered | A device appeared | The device |
device.updated | A field listed in X.9.12 under updatedSince changed | The device with updatedAt and consoleUrl |
device.deleted | A device was removed | id, tenantId, deviceName, deletedAt |
alert.opened | An alert was opened | The alert as in GET /v1/alerts/{id} |
alert.updated | An open alert fired again | The alert |
alert.resolved | An alert was resolved | The 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 default127.0.0.1:7480). The public port answers it like an unknown token, with401. - 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):
| Field | Meaning |
|---|---|
sourceType | file |
fileId | Id 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, fileUninstallArgs | Arguments 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. |
fileUninstallMode | none (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
fileStateshowschanged. targetOsfollows the file type andscriptShellthe target system; leave both out (anothertargetOsor ascriptShellanswers400). The application always runs elevated (requiresElevation: falseanswers400) and has no install or update script.versionanddetectionScriptare required.400 invalid_parameteralso for: a file collected from a device or belowdevices/, a file in thenetlockfolder (404withoutfile_server_netlock), an unsupported type, a file without a valid SHA-512, an uninstall mode the type does not offer,scriptwithoutuninstallScript, file fields on an application of another source.PATCH:fileIdpicks a (new) file and pins its current SHA-512; withoutfileIdthe stored file and hash are kept. Changing the arguments or the uninstall mode needsfile_server_enabledas 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).fileSha512does 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.
Related
- Chapter 5 — Automations — conditions, priority, evaluation.
- Chapter 8.4 — Custom Fields — definitions, levels, secrets.
- Script variables and custom fields in scripts.
- Write custom field values from a script.
- X.2 — Permission reference — the permissions the scopes map to.
- X.10 — Webhook signatures — verifying deliveries, managing subscriptions in the web console.
Platform Support
The operating systems and architectures the agent supports, further platforms the agent runs on, and the prerequisites for Remote Screen Control on Linux (Wayland) and macOS, and what Android devices support.
Webhook signatures
How NetLock RMM signs webhook requests with X-NetLock-Signature, how a receiver verifies them in C#, Python and Node.js, and how signed webhooks are managed in the web console.