REST API v1

The REST API exposes your inventory, missing updates, vulnerabilities, groups, automations, execution history and reports, and lets you run automations from your own tools (RMM, ticketing, CMDB, dashboards). Everything is scoped to the organization the credentials belong to.

The full list of operations, parameters and fields is in the generated API reference; the machine-readable OpenAPI 3.0 document is at /api/v1/openapi.json.

1. Create API credentials

Users & API Credentials → + New API Credentials. Give them a name (for example servicedesk-sync) and a role. The credentials get exactly the permissions of that role; the role must include API Access. The client secret is shown once: store it in your secret manager.

Recommended: one credential per integration, with a custom role limited to what it needs (for example endpoints.view and updates.view for a dashboard). Disable or delete credentials when the integration is retired; every write call they make is in the Audit Trail as api:<credential name>.

2. Get a token

OAuth 2.0 client-credentials grant. Tokens are valid for one hour; request a new one when a call answers 401.

curl -s -X POST https://<console>/api/oauth/token \
  -d "grant_type=client_credentials" \
  -d "client_id=<client id>" \
  -d "client_secret=<client secret>"

Response:

{ "access_token": "…", "token_type": "Bearer", "expires_in": 3600 }

The same endpoint accepts a JSON body or HTTP Basic authentication (client_id:client_secret). Wrong secrets are rate-limited per client id and per source IP: a 429 answer carries a Retry-After header.

3. Call the API

Send the token as a bearer header on every call:

curl -s https://<console>/api/v1/endpoints?limit=50 \
  -H "Authorization: Bearer <access_token>"

PowerShell:

$tok = (Invoke-RestMethod -Method Post -Uri "https://<console>/api/oauth/token" -Body @{ grant_type = "client_credentials"; client_id = "<client id>"; client_secret = "<client secret>" }).access_token
Invoke-RestMethod -Uri "https://<console>/api/v1/vulnerabilities?minCvss=9&kev=1" -Headers @{ Authorization = "Bearer $tok" }

Conventions

• Pagination: list endpoints take limit (1 to 500, default 100) and offset; they answer { items, total, limit, offset }. Loop until offset + items.length >= total.
• Timestamps are ISO 8601 in UTC; unknown values are null.
• Errors are JSON { "error": "<code>", "error_description": "<text>" } with the HTTP status: 400 malformed request, 401 missing or expired token, 403 permission missing on the role, 404 record not in your organization, 429 rate-limited.
• Ids are opaque strings; do not parse them. Update rows carry a stable key shared by the same update on every endpoint (the unit of approval).
• Writes (PATCH, DELETE, POST …/run) are audited; reads are not.

Endpoints at a glance

Examples

Endpoints that need a reboot:

curl -s "https://<console>/api/v1/endpoints?limit=500" -H "Authorization: Bearer $TOKEN" \
  | jq -r '.items[] | select(.pendingReboot) | .name'

Run the "Patch Tuesday" automation and follow it:

RUN=$(curl -s -X POST "https://<console>/api/v1/automations/<automation id>/run" -H "Authorization: Bearer $TOKEN" | jq -r .runId)
curl -s "https://<console>/api/v1/runs?runId=$RUN" -H "Authorization: Bearer $TOKEN"

Weekly CSV of missing critical updates for a ticketing system:

curl -s "https://<console>/api/v1/reports/missing-critical-updates?format=csv" -H "Authorization: Bearer $TOKEN" -o missing-critical.csv

Writing through the API

Approve every critical update in one call:

KEYS=$(curl -s "https://<console>/api/v1/updates?severity=Critical&limit=500" -H "Authorization: Bearer $TOKEN" | jq '[.items[] | {key, title}] | unique')
curl -s -X POST "https://<console>/api/v1/updates/approvals" -H "Authorization: Bearer $TOKEN" -H "content-type: application/json" -d "{\"keys\": $KEYS, \"status\": \"APPROVED\"}"

Webhooks

An alert rule can carry an HTTPS webhook URL. Every raised event is POSTed as JSON with the fields event, at, organization, rule (id, name, trigger), severity, title, detail and a ready-to-display text. Slack and Microsoft Teams incoming webhooks render the text field directly; ticketing tools and SIEMs use the structured fields. When the rule has a secret, the header X-Idolbe-Signature carries sha256=<HMAC-SHA256 of the raw body>; verify it before trusting the payload. Deliveries time out after 10 seconds and are not retried (the event itself stays in Alerts).

PowerShell module

PSIdolbePatch wraps the API with pipeline-friendly cmdlets (Get-IdolbeEndpoint, Get-IdolbeUpdate | Approve-IdolbeUpdate, Start-IdolbeAutomation, Invoke-IdolbeAction, Get-IdolbeReport -Key missing-updates -OutFile report.csv…). Tokens are refreshed automatically.

$dir = "$env:USERPROFILE\Documents\PowerShell\Modules\PSIdolbePatch"; New-Item -ItemType Directory -Force $dir | Out-Null
foreach ($f in 'PSIdolbePatch.psd1', 'PSIdolbePatch.psm1') { Invoke-WebRequest "https://<console>/tools/PSIdolbePatch/$f" -OutFile (Join-Path $dir $f) }
Import-Module PSIdolbePatch
Connect-IdolbePatch -Console https://<console> -ClientId <client id> -ClientSecret <client secret>
Get-IdolbeEndpoint | Where-Object pendingReboot | Select-Object name, os, lastSeenAt

Versioning

The path prefix /api/v1 is stable. Fields are added without notice; a field is only removed or renamed after at least six months of deprecation noted in the API reference. A future incompatible version would live under /api/v2 with v1 kept in parallel.