{"openapi":"3.0.3","info":{"title":"Idolbe Patch REST API","version":"1","description":"Read your inventory, missing updates, vulnerabilities and execution history, and run automations from your own tools.\n\nAuthenticate with OAuth 2.0 client credentials: create API credentials under Users & API Credentials, exchange them for a bearer token at POST /api/oauth/token (valid 1 hour), then send `Authorization: Bearer <token>` on every call.\n\nThe credentials inherit the permissions of their role; the role must include API Access. Lists are paginated with `limit`/`offset` (max 500 rows). Write calls are recorded in the Audit Trail as `api:<credential name>`.\n\nWrong secrets are rate-limited per client id and per source IP (HTTP 429 with a Retry-After header).","contact":{"name":"Idolbe Patch support","email":"contact@idolbe-ai.com","url":"https://vbhpatch.idolbe-ai.com/docs"}},"servers":[{"url":"https://vbhpatch.idolbe-ai.com"}],"tags":[{"name":"Authentication"},{"name":"Endpoints"},{"name":"Updates"},{"name":"Software"},{"name":"Vulnerabilities"},{"name":"Groups"},{"name":"Automations"},{"name":"Alerts"},{"name":"Reports"},{"name":"Meta"}],"paths":{"/api/oauth/token":{"post":{"operationId":"issueToken","tags":["Authentication"],"summary":"Exchange API credentials for a bearer token","description":"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.","security":[],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/TokenRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/TokenRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenResponse"}}}},"400":{"description":"Unsupported grant type or missing fields","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unknown client id, wrong secret or disabled credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many failed attempts (see the Retry-After header)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/endpoints":{"get":{"operationId":"listEndpoints","summary":"List endpoints","tags":["Endpoints"],"description":"Required permission: `endpoints.view` (plus `api.access`).","security":[{"oauth2":["endpoints.view"]}],"parameters":[{"name":"limit","in":"query","description":"Rows per page, 1–500 (default 100)","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"name":"offset","in":"query","description":"Rows to skip (default 0)","required":false,"schema":{"type":"integer","minimum":0,"default":0}},{"name":"q","in":"query","description":"Filter by hostname or display name (case-insensitive substring)","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Endpoint"}},"total":{"type":"integer","description":"Total rows matching the filters"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["items","total","limit","offset"]}}}},"401":{"description":"Missing, invalid or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The role of the credentials lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/endpoints/{id}":{"get":{"operationId":"getEndpoint","summary":"Get one endpoint with software, disks and missing updates","tags":["Endpoints"],"description":"Required permission: `endpoints.view` (plus `api.access`).","security":[{"oauth2":["endpoints.view"]}],"parameters":[{"name":"id","in":"path","description":"Endpoint id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EndpointDetail"}}}},"401":{"description":"Missing, invalid or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The role of the credentials lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such record in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateEndpoint","summary":"Rename or annotate an endpoint","tags":["Endpoints"],"description":"Required permission: `endpoints.manage` (plus `api.access`).","security":[{"oauth2":["endpoints.manage"]}],"parameters":[{"name":"id","in":"path","description":"Endpoint id","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EndpointPatch"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}}}}}},"400":{"description":"Invalid JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The role of the credentials lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such record in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteEndpoint","summary":"Remove an endpoint from the organization","tags":["Endpoints"],"description":"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.","security":[{"oauth2":["endpoints.manage"]}],"parameters":[{"name":"id","in":"path","description":"Endpoint id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}}}}}},"401":{"description":"Missing, invalid or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The role of the credentials lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such record in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/updates":{"get":{"operationId":"listUpdates","summary":"List missing updates (one row per endpoint × update)","tags":["Updates"],"description":"Required permission: `updates.view` (plus `api.access`).","security":[{"oauth2":["updates.view"]}],"parameters":[{"name":"limit","in":"query","description":"Rows per page, 1–500 (default 100)","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"name":"offset","in":"query","description":"Rows to skip (default 0)","required":false,"schema":{"type":"integer","minimum":0,"default":0}},{"name":"endpointId","in":"query","description":"Only this endpoint","required":false,"schema":{"type":"string"}},{"name":"severity","in":"query","description":"Critical, Important, Moderate, Low or Unspecified (applied after paging)","required":false,"schema":{"type":"string"}},{"name":"source","in":"query","description":"OS or THIRD_PARTY","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Update"}},"total":{"type":"integer","description":"Total rows matching the filters"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["items","total","limit","offset"]}}}},"401":{"description":"Missing, invalid or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The role of the credentials lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/software":{"get":{"operationId":"listSoftware","summary":"List installed software (one row per endpoint × application)","tags":["Software"],"description":"Required permission: `endpoints.view` (plus `api.access`).","security":[{"oauth2":["endpoints.view"]}],"parameters":[{"name":"limit","in":"query","description":"Rows per page, 1–500 (default 100)","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"name":"offset","in":"query","description":"Rows to skip (default 0)","required":false,"schema":{"type":"integer","minimum":0,"default":0}},{"name":"q","in":"query","description":"Filter by application name","required":false,"schema":{"type":"string"}},{"name":"endpointId","in":"query","description":"Only this endpoint","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SoftwareRow"}},"total":{"type":"integer","description":"Total rows matching the filters"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["items","total","limit","offset"]}}}},"401":{"description":"Missing, invalid or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The role of the credentials lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vulnerabilities":{"get":{"operationId":"listVulnerabilities","summary":"List vulnerabilities present on the fleet","tags":["Vulnerabilities"],"description":"Required permission: `vulnerabilities.view` (plus `api.access`).","security":[{"oauth2":["vulnerabilities.view"]}],"parameters":[{"name":"limit","in":"query","description":"Rows per page, 1–500 (default 100)","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"name":"offset","in":"query","description":"Rows to skip (default 0)","required":false,"schema":{"type":"integer","minimum":0,"default":0}},{"name":"minCvss","in":"query","description":"Minimum CVSS score","required":false,"schema":{"type":"number"}},{"name":"kev","in":"query","description":"1 = only CISA Known Exploited Vulnerabilities","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Vulnerability"}},"total":{"type":"integer","description":"Total rows matching the filters"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["items","total","limit","offset"]}}}},"401":{"description":"Missing, invalid or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The role of the credentials lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/groups":{"get":{"operationId":"listGroups","summary":"List endpoint groups","tags":["Groups"],"description":"Required permission: `endpoints.view` (plus `api.access`).","security":[{"oauth2":["endpoints.view"]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Group"}},"total":{"type":"integer"}},"required":["items","total"]}}}},"401":{"description":"Missing, invalid or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The role of the credentials lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createGroup","summary":"Create an endpoint group","tags":["Groups"],"description":"Static (machineIds) or dynamic (rules) group; uptime alerts optional.","security":[{"oauth2":["endpoints.manage"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GroupBody"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"group":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}}}}}}},"401":{"description":"Missing, invalid or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The role of the credentials lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/groups/{id}":{"patch":{"operationId":"updateGroup","summary":"Update an endpoint group","tags":["Groups"],"description":"Any subset of the create body. Built-in groups cannot be renamed or given criteria.","security":[{"oauth2":["endpoints.manage"]}],"parameters":[{"name":"id","in":"path","description":"Group id","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GroupBody"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"group":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}}}}}}},"401":{"description":"Missing, invalid or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The role of the credentials lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such record in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Built-in group","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteGroup","summary":"Delete an endpoint group","tags":["Groups"],"description":"Required permission: `endpoints.manage` (plus `api.access`).","security":[{"oauth2":["endpoints.manage"]}],"parameters":[{"name":"id","in":"path","description":"Group id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}}}}}},"401":{"description":"Missing, invalid or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The role of the credentials lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such record in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Built-in group","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/automations":{"get":{"operationId":"listAutomations","summary":"List automations","tags":["Automations"],"description":"Required permission: `automations.view` (plus `api.access`).","security":[{"oauth2":["automations.view"]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Automation"}},"total":{"type":"integer"}},"required":["items","total"]}}}},"401":{"description":"Missing, invalid or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The role of the credentials lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createAutomation","summary":"Create an automation","tags":["Automations"],"description":"Same body as the console wizard. scheduleKind NOW runs the action immediately and returns the run id.","security":[{"oauth2":["automations.manage"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationBody"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"automation":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"runId":{"type":"string","nullable":true},"queued":{"type":"integer"}}}}}}}},"401":{"description":"Missing, invalid or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The role of the credentials lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/automations/{id}":{"get":{"operationId":"getAutomation","summary":"Get one automation with its payload","tags":["Automations"],"description":"Required permission: `automations.view` (plus `api.access`).","security":[{"oauth2":["automations.view"]}],"parameters":[{"name":"id","in":"path","description":"Automation id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Automation"}}}},"401":{"description":"Missing, invalid or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The role of the credentials lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such record in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateAutomation","summary":"Enable, pause, rename or fully edit an automation","tags":["Automations"],"description":"Send { enabled, name, description } for a light change, or a full AutomationBody (with actionType) to replace every field.","security":[{"oauth2":["automations.manage"]}],"parameters":[{"name":"id","in":"path","description":"Automation id","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/AutomationPatch"},{"$ref":"#/components/schemas/AutomationBody"}]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"automation":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}}}}}}},"401":{"description":"Missing, invalid or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The role of the credentials lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such record in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteAutomation","summary":"Delete an automation","tags":["Automations"],"description":"Required permission: `automations.manage` (plus `api.access`).","security":[{"oauth2":["automations.manage"]}],"parameters":[{"name":"id","in":"path","description":"Automation id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}}}}}},"401":{"description":"Missing, invalid or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The role of the credentials lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such record in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/actions":{"post":{"operationId":"queueAction","summary":"Run an action now on endpoints","tags":["Automations"],"description":"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\".","security":[{"oauth2":["automations.run"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionBody"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"runId":{"type":"string"},"queued":{"type":"integer","description":"Commands sent to endpoints"}}}}}},"401":{"description":"Missing, invalid or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The role of the credentials lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No valid endpoints","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or nothing to install","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/updates/approvals":{"post":{"operationId":"setApprovals","summary":"Approve, decline or reset updates","tags":["Updates"],"description":"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.","security":[{"oauth2":["updates.manage"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApprovalBody"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"count":{"type":"integer"},"status":{"type":"string"},"changed":{"type":"integer","description":"Decisions written, or for NEW the decisions deleted"}}}}}},"401":{"description":"Missing, invalid or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The role of the credentials lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/alerts":{"get":{"operationId":"listAlertRules","summary":"List alert rules","tags":["Alerts"],"description":"Required permission: `reports.view` (plus `api.access`).","security":[{"oauth2":["reports.view"]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AlertRule"}},"total":{"type":"integer"}},"required":["items","total"]}}}},"401":{"description":"Missing, invalid or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The role of the credentials lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createAlertRule","summary":"Create an alert rule","tags":["Alerts"],"description":"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).","security":[{"oauth2":["reports.manage"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertRuleBody"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"rule":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}}}}}}},"401":{"description":"Missing, invalid or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The role of the credentials lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/automations/{id}/run":{"post":{"operationId":"runAutomation","summary":"Run an automation now","tags":["Automations"],"description":"Queues the automation's action on its current targets and returns the run id (follow it with /api/v1/runs?runId=).","security":[{"oauth2":["automations.run"]}],"parameters":[{"name":"id","in":"path","description":"Automation id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"runId":{"type":"string"},"queued":{"type":"integer","description":"Endpoints the action was queued on"}}}}}},"401":{"description":"Missing, invalid or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The role of the credentials lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such record in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/runs":{"get":{"operationId":"listRuns","summary":"Execution history","tags":["Automations"],"description":"Without runId: the most recent runs (automations and ad-hoc actions). With runId: the per-endpoint results of that run.","security":[{"oauth2":["automations.view"]}],"parameters":[{"name":"runId","in":"query","description":"Return the per-endpoint commands of this run instead of the run list","required":false,"schema":{"type":"string"}},{"name":"automationId","in":"query","description":"Only runs of this automation","required":false,"schema":{"type":"string"}},{"name":"endpointId","in":"query","description":"Only runs that touched this endpoint","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"Max runs, 1–500 (default 100)","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":100}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Run"}},"total":{"type":"integer"}},"required":["items","total"]},{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/RunCommand"}},"total":{"type":"integer"}},"required":["items","total"]}]}}}},"401":{"description":"Missing, invalid or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The role of the credentials lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such record in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/reports/{key}":{"get":{"operationId":"getReport","summary":"Read a built-in report (JSON or CSV)","tags":["Reports"],"description":"Use key `_list` for the catalog of reports.","security":[{"oauth2":["reports.view"]}],"parameters":[{"name":"key","in":"path","required":true,"description":"Report key (see _list)","schema":{"type":"string","enum":["_list","endpoints","installed-software","web-browsers","instant-messengers","cloud-storage-apps","software-by-endpoint","hardware-inventory","disk-drives","disks-summary","network-adapters","monitors","physical-memory","firmware","processors","motherboards","sound-devices","scsi-controllers","windows-drivers","printers","update-summary","weekly-update-summary","missing-updates","missing-critical-updates","missing-third-party","installed-updates","reboots","update-status","windows-update-settings","win11-compatibility","windows-update-history","update-statistic","antivirus-status","bitlocker-status","local-user-accounts","local-groups","group-membership","profiles-by-computer","local-administrators","shared-folders","logged-on-users","offline-endpoints","low-disk-space","computer-ad-domains","environment-variables","to-internet-domains","bitlocker-key","logical-disks","disk-volumes","os-information","os-install-dates","computer-time-zones","running-processes","routing-tables","to-tcp-ip-addresses","services","startup-items","applied-gpo","boot-configuration","agent-configuration","vulnerabilities","vulnerable-software","compensating-controls","moveit-vulnerability","webp-vulnerability","cisa-kev","vulnerabilities-by-endpoint","compliance","windows-hot-fixes","cyber-essentials-email","cyber-essentials-office","cyber-essentials-web-browsers","ms-outlook-versions","hw-manufacturers","logon-statistics","profiles-by-user","sd-card-usage","usb-disk-usage","open-hidden-shares","local-time","windows-event-logs","process-memory-stats","disk-partitions","disks-without-bitlocker","ntfs-disk-quotas","all-critical-vulnerabilities","vulnerability-summary","cve-2025-5480-status"]}},{"name":"format","in":"query","description":"csv for a text/csv download instead of JSON","required":false,"schema":{"type":"string","enum":["csv"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Report"},{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ReportMeta"}},"total":{"type":"integer"}},"required":["items","total"]}]}},"text/csv":{"schema":{"type":"string"}}}},"401":{"description":"Missing, invalid or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The role of the credentials lacks the required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such record in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/openapi.json":{"get":{"operationId":"getOpenApi","tags":["Meta"],"summary":"This document","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"components":{"securitySchemes":{"oauth2":{"type":"oauth2","description":"Client credentials created under Users & API Credentials.","flows":{"clientCredentials":{"tokenUrl":"https://vbhpatch.idolbe-ai.com/api/oauth/token","scopes":{"endpoints.view":"Read endpoints, groups and installed software","endpoints.manage":"Rename, annotate or remove endpoints","updates.view":"Read missing updates","vulnerabilities.view":"Read vulnerabilities","automations.view":"Read automations and execution history","automations.run":"Run automations","updates.manage":"Approve, decline or reset updates","reports.view":"Read reports and alert rules","reports.manage":"Create reports and alert rules"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable code, e.g. invalid_token, insufficient_scope, not_found, invalid_json"},"error_description":{"type":"string","nullable":true}},"required":["error"]},"TokenRequest":{"type":"object","properties":{"grant_type":{"type":"string","enum":["client_credentials"]},"client_id":{"type":"string"},"client_secret":{"type":"string"}},"required":["grant_type","client_id","client_secret"]},"TokenResponse":{"type":"object","properties":{"access_token":{"type":"string"},"token_type":{"type":"string","enum":["Bearer"]},"expires_in":{"type":"integer","description":"Seconds until expiry"}},"required":["access_token","token_type","expires_in"]},"Endpoint":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","description":"Display name, or hostname when none is set"},"hostname":{"type":"string"},"platform":{"type":"string","description":"windows, linux or macos"},"status":{"type":"string","enum":["connected","disconnected"]},"os":{"type":"string","nullable":true},"osVersion":{"type":"string","nullable":true},"osBuild":{"type":"string","nullable":true},"type":{"type":"string","enum":["server","workstation"]},"domain":{"type":"string","nullable":true},"adOu":{"type":"string","nullable":true},"user":{"type":"string","description":"Last logged-on user","nullable":true},"manufacturer":{"type":"string","nullable":true},"model":{"type":"string","nullable":true},"serialNumber":{"type":"string","nullable":true},"cpu":{"type":"string","nullable":true},"cores":{"type":"integer","nullable":true},"ramGB":{"type":"number","nullable":true},"ipAddresses":{"type":"array","items":{"type":"string"}},"macAddresses":{"type":"array","items":{"type":"string"}},"antivirus":{"type":"string","nullable":true},"pendingReboot":{"type":"boolean"},"agentVersion":{"type":"string","nullable":true},"attributes":{"type":"object","description":"Custom attributes attr1…attr30","additionalProperties":{"type":"string"}},"lastBootAt":{"type":"string","nullable":true,"format":"date-time"},"lastSeenAt":{"type":"string","nullable":true,"format":"date-time"},"enrolledAt":{"type":"string","nullable":true,"format":"date-time"},"comment":{"type":"string","nullable":true}}},"EndpointDetail":{"allOf":[{"$ref":"#/components/schemas/Endpoint"},{"type":"object","properties":{"disks":{"type":"array","items":{"type":"object","properties":{"drive":{"type":"string"},"sizeGB":{"type":"number","nullable":true},"freeGB":{"type":"number","nullable":true}}}},"software":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string","nullable":true},"publisher":{"type":"string","nullable":true},"installDate":{"type":"string","nullable":true}}}},"missingUpdates":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"kb":{"type":"string","nullable":true},"severity":{"type":"string","nullable":true},"source":{"type":"string"},"wingetId":{"type":"string","nullable":true},"installedVersion":{"type":"string","nullable":true},"latestVersion":{"type":"string","nullable":true},"rebootRequired":{"type":"boolean"}}}}}}]},"EndpointPatch":{"type":"object","properties":{"name":{"type":"string","description":"Display name (empty string clears it)"},"comment":{"type":"string"},"attributes":{"type":"object","description":"Only keys attr1…attr30 are accepted","additionalProperties":{"type":"string"}}}},"Update":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string","description":"Stable key shared by the same update on every endpoint (approval scope)"},"endpointId":{"type":"string"},"endpoint":{"type":"string"},"title":{"type":"string"},"kb":{"type":"string","nullable":true},"severity":{"type":"string","enum":["Critical","Important","Moderate","Low","Unspecified"]},"source":{"type":"string","description":"OS - Mandatory, OS - Optional or Applications"},"categories":{"type":"array","items":{"type":"string"}},"wingetId":{"type":"string","nullable":true},"installedVersion":{"type":"string","nullable":true},"latestVersion":{"type":"string","nullable":true},"rebootRequired":{"type":"boolean"},"releaseDate":{"type":"string","nullable":true,"format":"date-time"},"detectedAt":{"type":"string","nullable":true,"format":"date-time"},"approval":{"type":"string","enum":["NEW","APPROVED","DECLINED"]}}},"SoftwareRow":{"type":"object","properties":{"endpointId":{"type":"string"},"endpoint":{"type":"string"},"name":{"type":"string"},"version":{"type":"string","nullable":true},"publisher":{"type":"string","nullable":true},"installDate":{"type":"string","nullable":true},"installedFor":{"type":"string","nullable":true},"installType":{"type":"string","nullable":true}}},"Vulnerability":{"type":"object","properties":{"cveId":{"type":"string"},"cvssScore":{"type":"number","nullable":true},"severity":{"type":"string","nullable":true},"cisaKev":{"type":"boolean"},"ransomware":{"type":"boolean"},"publishedAt":{"type":"string","nullable":true,"format":"date-time"},"remediationStatus":{"type":"string","description":"Overdue, Due soon or Due later, at the time of the request","nullable":true},"remediationDeadline":{"type":"string","nullable":true,"format":"date-time"},"nvdUrl":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"software":{"type":"array","description":"Affected products found on the fleet","items":{"type":"string"}},"endpoints":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}}}}},"Group":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"system":{"type":"boolean","description":"Built-in group (All Endpoints, New Endpoints, …)"},"kind":{"type":"string","description":"STATIC or DYNAMIC"},"members":{"type":"integer"}}},"Automation":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"action":{"type":"string","description":"RUN_SCRIPT, DEPLOY_UPDATES, REBOOT, DEPLOY_SOFTWARE or UNINSTALL_SOFTWARE"},"actionLabel":{"type":"string"},"kind":{"type":"string","description":"SIMPLE or RING"},"scheduleKind":{"type":"string","nullable":true},"freq":{"type":"string","description":"DAILY, WEEKLY, MONTHLY or PATCH_TUESDAY","nullable":true},"atTime":{"type":"string","nullable":true},"weekday":{"type":"integer","nullable":true},"monthDay":{"type":"integer","nullable":true},"offsetDays":{"type":"integer","description":"Days after Patch Tuesday when freq is PATCH_TUESDAY"},"windowMinutes":{"type":"integer","description":"Maintenance window: minutes after the slot during which the run may still start; null = no limit","nullable":true},"runAt":{"type":"string","nullable":true,"format":"date-time"},"enabled":{"type":"boolean"},"targetMode":{"type":"string","description":"GROUP or ENDPOINTS"},"groupId":{"type":"string","nullable":true},"endpointIds":{"type":"array","items":{"type":"string"}},"lastRunAt":{"type":"string","nullable":true,"format":"date-time"},"nextRunAt":{"type":"string","nullable":true,"format":"date-time"},"createdBy":{"type":"string","nullable":true}}},"Run":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"actionType":{"type":"string"},"status":{"type":"string","description":"RUNNING, COMPLETED, FAILED or STOPPED"},"startedAt":{"type":"string","nullable":true,"format":"date-time"},"finishedAt":{"type":"string","nullable":true,"format":"date-time"},"total":{"type":"integer"},"succeeded":{"type":"integer"},"failed":{"type":"integer"},"createdBy":{"type":"string","nullable":true},"automationId":{"type":"string","nullable":true},"automationName":{"type":"string","nullable":true},"detail":{"type":"string","nullable":true}}},"RunCommand":{"type":"object","properties":{"id":{"type":"string"},"machineId":{"type":"string"},"endpoint":{"type":"string"},"status":{"type":"string","description":"PENDING, RUNNING, SUCCESS, FAILED or CANCELLED"},"startedAt":{"type":"string","nullable":true,"format":"date-time"},"finishedAt":{"type":"string","nullable":true,"format":"date-time"},"result":{"type":"string","description":"Execution log","nullable":true},"createdAt":{"type":"string","nullable":true,"format":"date-time"}}},"GroupRule":{"type":"object","properties":{"field":{"type":"string","description":"hostname, os, osVersion, platform, domain, type, arch, antivirus, reboot, agentVersion, attr1…attr30, …"},"op":{"type":"string","enum":["contains","notContains","equals","notEquals","startsWith","endsWith","isTrue","isFalse"]},"value":{"type":"string"}},"required":["field","op"]},"GroupBody":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"matchAll":{"type":"boolean","description":"true = every include rule must match"},"rules":{"type":"array","description":"Dynamic include criteria","items":{"$ref":"#/components/schemas/GroupRule"}},"excludeRules":{"type":"array","items":{"$ref":"#/components/schemas/GroupRule"}},"machineIds":{"type":"array","description":"Manual members (static group)","items":{"type":"string"}},"offlineAlertMinutes":{"type":"integer","description":"Uptime alert after N minutes offline","nullable":true},"onlineAlert":{"type":"boolean","description":"Alert when a member comes back online"}},"required":["name"]},"AutomationBody":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"kind":{"type":"string","description":"SCHEDULED or RING","enum":["SCHEDULED","RING"]},"actionType":{"type":"string","enum":["RUN_SCRIPT","DEPLOY_UPDATES","REBOOT","DEPLOY_SOFTWARE","UNINSTALL_SOFTWARE"]},"payload":{"type":"object","description":"Action payload as built by the console wizard. DEPLOY_UPDATES filters use the Update Approval labels (an application version is a Regular or Security Update) when the payload carries \"filterVersion\": 2. Without it the earlier labels apply: applications are picked only by the type \"Application Updates\", so types [\"Regular Updates\"] means Windows updates only, and severities read every application version as Unspecified, so severities [\"Critical\"] means Windows updates only"},"targetMode":{"type":"string","enum":["all","group","endpoints"]},"groupId":{"type":"string"},"endpointIds":{"type":"array","items":{"type":"string"}},"scheduleKind":{"type":"string","enum":["NOW","ONCE","RECURRING"]},"runAt":{"type":"string","description":"ISO date-time for ONCE"},"freq":{"type":"string","enum":["DAILY","WEEKLY","MONTHLY","PATCH_TUESDAY"]},"atTime":{"type":"string","description":"HH:MM"},"weekday":{"type":"integer","description":"0 = Sunday"},"monthDay":{"type":"integer","description":"1–28"},"offsetDays":{"type":"integer","description":"Days after Patch Tuesday"},"windowMinutes":{"type":"integer","description":"Maintenance window","nullable":true},"enabled":{"type":"boolean"},"startDate":{"type":"string","description":"RING: first ring date"},"rings":{"type":"array","description":"RING stages","items":{"type":"object","properties":{"name":{"type":"string"},"groupId":{"type":"string"},"offsetDays":{"type":"integer"}}}}},"required":["name","actionType"]},"AutomationPatch":{"type":"object","properties":{"enabled":{"type":"boolean"},"name":{"type":"string"},"description":{"type":"string"}}},"ActionBody":{"type":"object","properties":{"endpointIds":{"type":"array","items":{"type":"string"}},"type":{"type":"string","enum":["RUN_SCRIPT","DEPLOY_UPDATES","REBOOT","DEPLOY_SOFTWARE","UNINSTALL_SOFTWARE"]},"label":{"type":"string"},"payload":{"type":"object","description":"RUN_SCRIPT: { script, language } or { scriptId, parameters: { Name: value } } (a Script Library script, its current code and reboot exit codes); DEPLOY_UPDATES: { mode: all | selected (keys) | filters ({ severities, types, sources }), approvalMode, filterVersion }; REBOOT: { message, timeoutSeconds }; DEPLOY_SOFTWARE: { wingetId } or { url, args }; UNINSTALL_SOFTWARE: { name }. DEPLOY_UPDATES filters use the Update Approval labels (an application version is a Regular or Security Update) when the payload carries \"filterVersion\": 2. Without it the earlier labels apply: applications are picked only by the type \"Application Updates\", so types [\"Regular Updates\"] means Windows updates only, and severities read every application version as Unspecified, so severities [\"Critical\"] means Windows updates only"}},"required":["endpointIds","type"]},"ApprovalBody":{"type":"object","properties":{"keys":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"title":{"type":"string"}},"required":["key"]}},"status":{"type":"string","enum":["APPROVED","DECLINED","NEW"]}},"required":["keys","status"]},"AlertRule":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"trigger":{"type":"string"},"threshold":{"type":"integer"},"enabled":{"type":"boolean"},"emailTo":{"type":"string","nullable":true},"webhookUrl":{"type":"string","nullable":true},"hasWebhookSecret":{"type":"boolean"},"reportKey":{"type":"string","nullable":true},"events":{"type":"integer","description":"Events raised so far"},"createdAt":{"type":"string","nullable":true,"format":"date-time"}}},"AlertRuleBody":{"type":"object","properties":{"name":{"type":"string"},"trigger":{"type":"string","description":"GROUP_UPTIME, NEW_ENDPOINT, CRITICAL_VULN, MISSING_CRITICAL_UPDATE, ENDPOINT_OFFLINE, REBOOT_REQUIRED or REPORT_ROWS"},"threshold":{"type":"integer"},"emailTo":{"type":"string","description":"Comma-separated recipients"},"webhookUrl":{"type":"string","description":"HTTPS URL"},"webhookSecret":{"type":"string"},"reportKey":{"type":"string","description":"REPORT_ROWS: report key"}},"required":["name","trigger"]},"ReportMeta":{"type":"object","properties":{"key":{"type":"string"},"title":{"type":"string"},"category":{"type":"string"},"description":{"type":"string"}}},"Report":{"type":"object","properties":{"title":{"type":"string"},"columns":{"type":"array","items":{"type":"string"}},"rows":{"type":"array","description":"One array per row, in column order","items":{"type":"array","items":{}}},"total":{"type":"integer"},"collectedAt":{"type":"string","nullable":true,"format":"date-time"}}}}}}