Skip to main content

REST API

The REST API lives under /api/v1. The web interface uses it, and so can scripts, exports and other systems. The complete list of requests, parameters and responses is in the interactive Swagger UI of your server at /swagger/index.html, and the OpenAPI specification of this version is downloadable here.

Authentication​

There are three ways to authenticate. Send the credential in the Authorization header as Bearer <token>.

CredentialObtainedUsed by
Session tokenPOST /api/v1/auth/login with an e-mail address and a passwordThe web interface, and scripts that log in. Lasts SESSION_TTL.
Personal token, vopt_...The Account page, or POST /api/v1/auth/tokensScripts, exports, AI assistants. Has the roles and scope of its user.
Agent key, vopa_...Registration of the agentAgents only. Covered in the agent protocol.

Log in with a script:

TOKEN=$(curl -s -X POST https://vop.example.com/api/v1/auth/login \
-H 'Content-Type: application/json' \
-d '{"email":"admin@example.com","password":"..."}' | jq -r .token)

Conventions​

  • Bodies are JSON unless an endpoint takes a file, such as the upload of an agent release.
  • Lists are paged: the response holds items, total, page and pageSize. Ask for a page with the page and pageSize parameters.
  • Filters are query parameters with the names of the findings page: severity, cluster, namespace, agentId, asset, assetId, kind, pod, container, image, package, packageType, version, cve, fixable, minCvss, since and q. A comma separates several values, such as severity=critical,high. since takes an RFC 3339 time or a date.
  • Errors are JSON objects with an error message and the HTTP status code.
  • Scope applies. Every list and count returns only what the user may see. A missing item may be out of scope rather than absent.
  • Permissions apply. A call that the user's roles do not allow returns 403 Forbidden.

Examples​

# The findings of a cluster, critical and high, first page of 50
curl -H "Authorization: Bearer $TOKEN" \
'https://vop.example.com/api/v1/findings?severity=critical,high&cluster=prod&page=1&pageSize=50'

# A PDF export with the filters of the dashboard
curl -H "Authorization: Bearer $TOKEN" -o findings.pdf \
'https://vop.example.com/api/v1/export/findings?format=pdf&severity=critical,high&cluster=prod'

# A SARIF file for the code scanning tab of a CI pipeline
curl -H "Authorization: Bearer $TOKEN" -o findings.sarif \
'https://vop.example.com/api/v1/export/findings?format=sarif&severity=critical,high'

# Start a scan
curl -X POST -H "Authorization: Bearer $TOKEN" 'https://vop.example.com/api/v1/scans?full=false'

Groups of endpoints​

GroupExamplesPermission
AuthenticationPOST /auth/login, GET /auth/me, POST /auth/password, /auth/tokensAny signed-in user
InventoryGET /dashboard/summary, /findings, /findings/facets, /packages, /packages/{id}, /assets, /export/findings, /export/packages, /export/vexinventory.view
TriageGET /finding-decisions, PUT /finding-decisions, DELETE /finding-decisions/{id}inventory.view to read, findings.triage to change
AgentsGET /agents, POST /agents, PATCH /agents/{id}, POST /agents/{id}/rotate-key, /cluster-tokens, /enroll-tokens, /agent-releases, /agent-updatesagents.view, agents.manage
Scans and tasksGET /scans, POST /scans, GET /task-runs, GET /tasks, PUT /tasks/{name}, POST /tasks/{name}/runscans.view, scans.run, tasks.manage
ReportsGET /reports, POST /reports, GET /reports/{id}/download, /report-templatesreports.view, reports.manage
CPE mappingsGET /cpe-mappings, POST /cpe-mappings, GET /nvd-cpes/search, POST /nvd-cpes/importcpe.view, cpe.manage
Alerts/alert-channels, /alert-rules, /alert-events, POST /alert-channels/{id}/testalerts.view, alerts.manage
Settings/settings/agent-updates, /settings/nvd, /settings/ai, POST /settings/ai/testsettings.manage
Users and roles/users, /roles, /permissionsusers.manage, roles.manage
InstallGET /install/linux.sh, /install/windows.ps1, /install/macos.sh, POST /install/registerEnrollment link
AgentPOST /agent/register, /agent/heartbeat, /agent/inventoryAgent key or cluster token

Each group is tagged in the Swagger UI. Authentication for the agent group is the agent's key, not a user token.

Specification​

The OpenAPI document is generated from the handler annotations of the server. Generate clients from it with any OpenAPI generator. The file is regenerated with make swagger, and the copy on this site is refreshed on every build of the documentation.