API reference

POST/api/oauth/token

Exchange API credentials for a bearer token

OAuth 2.0 client-credentials grant. Send the credentials as a form body, as JSON, or with HTTP Basic authentication (client_id:client_secret). Tokens expire after one hour; request a new one when a call answers 401.

Request body (JSON): TokenRequest

GET/api/v1/endpoints

List endpoints

Required permission: endpoints.view (plus api.access).

GET/api/v1/endpoints/{id}

Get one endpoint with software, disks and missing updates

Required permission: endpoints.view (plus api.access).

PATCH/api/v1/endpoints/{id}

Rename or annotate an endpoint

Required permission: endpoints.manage (plus api.access).

Request body (JSON): EndpointPatch

DELETE/api/v1/endpoints/{id}

Remove an endpoint from the organization

Removes the record and tells the agent to uninstall itself at its next check-in (agents 0.11.4 and later). Reinstalling the agent enrolls the computer again.

GET/api/v1/updates

List missing updates (one row per endpoint × update)

Required permission: updates.view (plus api.access).

GET/api/v1/software

List installed software (one row per endpoint × application)

Required permission: endpoints.view (plus api.access).

GET/api/v1/vulnerabilities

List vulnerabilities present on the fleet

Required permission: vulnerabilities.view (plus api.access).

GET/api/v1/groups

List endpoint groups

Required permission: endpoints.view (plus api.access).

POST/api/v1/groups

Create an endpoint group

Static (machineIds) or dynamic (rules) group; uptime alerts optional.

Request body (JSON): GroupBody

PATCH/api/v1/groups/{id}

Update an endpoint group

Any subset of the create body. Built-in groups cannot be renamed or given criteria.

Request body (JSON): GroupBody

DELETE/api/v1/groups/{id}

Delete an endpoint group

Required permission: endpoints.manage (plus api.access).

GET/api/v1/automations

List automations

Required permission: automations.view (plus api.access).

POST/api/v1/automations

Create an automation

Same body as the console wizard. scheduleKind NOW runs the action immediately and returns the run id.

Request body (JSON): AutomationBody

GET/api/v1/automations/{id}

Get one automation with its payload

Required permission: automations.view (plus api.access).

PATCH/api/v1/automations/{id}

Enable, pause, rename or fully edit an automation

Send { enabled, name, description } for a light change, or a full AutomationBody (with actionType) to replace every field.

Request body (JSON): AutomationPatch or AutomationBody

DELETE/api/v1/automations/{id}

Delete an automation

Required permission: automations.manage (plus api.access).

POST/api/v1/actions

Run an action now on endpoints

Queues RUN_SCRIPT, DEPLOY_UPDATES, REBOOT, DEPLOY_SOFTWARE or UNINSTALL_SOFTWARE on the listed endpoints (ids outside the organization are ignored). Appears in History as one run. A DEPLOY_UPDATES that installs nothing on any endpoint (no matching update, or no package source for it) is refused with 422; an endpoint with nothing to install in a run that installs elsewhere gets a CANCELLED command whose result starts with "Nothing to install".

Request body (JSON): ActionBody

POST/api/v1/updates/approvals

Approve, decline or reset updates

keys are the stable Update.key values from GET /api/v1/updates. A decision covers exactly one version: APPROVED and DECLINED refuse a third-party key without @<version> (422). A per-architecture or raw-spelling key (winget:Microsoft.VCRedist.2015+.x64@…, winget:Zoom.Zoom.EXE@7.1.8 (46825)) is stored under the key GET returns for it. NEW clears the decision stored under each key.

Request body (JSON): ApprovalBody

GET/api/v1/alerts

List alert rules

Required permission: reports.view (plus api.access).

POST/api/v1/alerts

Create an alert rule

Email recipients and/or an HTTPS webhook (JSON POST per event, X-Idolbe-Signature when a secret is set; Slack and Teams incoming webhooks accept the payload).

Request body (JSON): AlertRuleBody

POST/api/v1/automations/{id}/run

Run an automation now

Queues the automation's action on its current targets and returns the run id (follow it with /api/v1/runs?runId=).

GET/api/v1/runs

Execution history

Without runId: the most recent runs (automations and ad-hoc actions). With runId: the per-endpoint results of that run.

GET/api/v1/reports/{key}

Read a built-in report (JSON or CSV)

Use key _list for the catalog of reports.

GET/api/v1/openapi.json

This document

Error

TokenRequest

TokenResponse

Endpoint

EndpointDetail

Everything in Endpoint, plus:

EndpointPatch

Update

SoftwareRow

Vulnerability

Group

Automation

Run

RunCommand

GroupRule

GroupBody

AutomationBody

AutomationPatch

ActionBody

ApprovalBody

AlertRule

AlertRuleBody

ReportMeta

Report