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>.
| Credential | Obtained | Used by |
|---|---|---|
| Session token | POST /api/v1/auth/login with an e-mail address and a password | The web interface, and scripts that log in. Lasts SESSION_TTL. |
Personal token, vopt_... | The Account page, or POST /api/v1/auth/tokens | Scripts, exports, AI assistants. Has the roles and scope of its user. |
Agent key, vopa_... | Registration of the agent | Agents 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,pageandpageSize. Ask for a page with thepageandpageSizeparameters. - 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,sinceandq. A comma separates several values, such asseverity=critical,high.sincetakes an RFC 3339 time or a date. - Errors are JSON objects with an
errormessage 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
| Group | Examples | Permission |
|---|---|---|
| Authentication | POST /auth/login, GET /auth/me, POST /auth/password, /auth/tokens | Any signed-in user |
| Inventory | GET /dashboard/summary, /findings, /findings/facets, /packages, /packages/{id}, /assets, /export/findings, /export/packages, /export/vex | inventory.view |
| Triage | GET /finding-decisions, PUT /finding-decisions, DELETE /finding-decisions/{id} | inventory.view to read, findings.triage to change |
| Agents | GET /agents, POST /agents, PATCH /agents/{id}, POST /agents/{id}/rotate-key, /cluster-tokens, /enroll-tokens, /agent-releases, /agent-updates | agents.view, agents.manage |
| Scans and tasks | GET /scans, POST /scans, GET /task-runs, GET /tasks, PUT /tasks/{name}, POST /tasks/{name}/run | scans.view, scans.run, tasks.manage |
| Reports | GET /reports, POST /reports, GET /reports/{id}/download, /report-templates | reports.view, reports.manage |
| CPE mappings | GET /cpe-mappings, POST /cpe-mappings, GET /nvd-cpes/search, POST /nvd-cpes/import | cpe.view, cpe.manage |
| Alerts | /alert-channels, /alert-rules, /alert-events, POST /alert-channels/{id}/test | alerts.view, alerts.manage |
| Settings | /settings/agent-updates, /settings/nvd, /settings/ai, POST /settings/ai/test | settings.manage |
| Users and roles | /users, /roles, /permissions | users.manage, roles.manage |
| Install | GET /install/linux.sh, /install/windows.ps1, /install/macos.sh, POST /install/register | Enrollment link |
| Agent | POST /agent/register, /agent/heartbeat, /agent/inventory | Agent 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.