SecurityVault
Request a demo
Browse documentation

API reference.

JSON over HTTPS under /api/v2. Request bodies are strictly validated — unknown fields are rejected and lengths are capped — and every organisation-scoped call carries the organisation header.

Base path /api/v2Auth Bearer tokenOrganisation X-Organization-IDUpdated October 2026

Authentication

Send a bearer token and your organisation id on every organisation-scoped request. The server takes the acting organisation from the verified session and this header — never from a query parameter.

Authorization: Bearer <token>
X-Organization-ID: <your-organisation-id>
Content-Type: application/json

Ways to obtain a bearer token:

  • Device flow — the OAuth 2.0 device authorisation grant used by the CLI: POST /api/v2/auth/device/code, approve in the browser, then poll POST /api/v2/auth/device/token.
  • Pipeline OIDC — exchange your CI provider's OIDC token at POST /api/v2/ci/pipeline/token-oidc.
  • Console sessions — short-lived signed access tokens, with the refresh token held in an HttpOnly cookie out of reach of page scripts.

Signed API-key requests

Endpoints that accept machine credentials, such as the findings list, also take an API key. An API-key request is signed rather than sent as a bearer secret: compute an HMAC-SHA256 with the key secret over the method, the path (without the query string), the Date header, a fresh nonce and the SHA-256 of the body, joined by newlines, and send the hex digest.

Authorization: SV-KEY <key-id>:<hex HMAC-SHA256 signature>
Date: Mon, 05 Oct 2026 09:12:41 GMT       # within five minutes of server time
X-SV-Nonce: <unique value per request>   # never reused

# string to sign
GET\n/api/v2/findings\n<Date>\n<X-SV-Nonce>\n<sha256 hex of the request body>

Core endpoints

MethodPathDescription
POST/api/v2/scansCreate a scan for a repository, image or other target. Omit tools to use the automatic tool plan.
GET/api/v2/scans/{scan_id}Scan status and per-tool outcomes.
GET/api/v2/scans/{scan_id}/sbom/cyclonedxCycloneDX SBOM produced by the scan.
GET/api/v2/scan-requests/{id}/timelineProgress and state changes for a multi-target scan request.
GET/api/v2/findingsList findings with severity, status and scope filters; cursor pagination.
GET/api/v2/findings/{id}/detailFinding with typed evidence (code span, dataflow path, dependency path, config path, request trace, exploit proof, artifact hash).
GET/api/v2/findings/{id}/lineageLineage view: satisfied hops with provenance, missing hops with a reason, and conflicts.
POST/api/v2/findings/{id}/dispositionRecord a human verdict, with a mandatory reason code from GET /api/v2/disposition/reason-codes.
POST/api/v2/findings/{id}/verify-fixedRequest re-verification of a fix.
POST/api/v2/findings/{id}/fix-prOpen an advisory fix pull request from a remediation template.
GET/api/v2/sca/dependenciesDependencies with reachability hints and licences.
POST/api/v2/sca/sboms/generateGenerate an SBOM for a target in CycloneDX or SPDX.
GET/api/v2/sca/sbomsList SBOMs held for your organisation.
GET/api/v2/imagesImages by registry, with per-digest results and the workloads running them.
POST/api/v2/images/{id}/scanScan an image by digest.
GET/api/v2/repositories/repos/{id}/overviewRepository coverage, recent scans and settings.
POST/api/v2/ci/gate/evaluateEvaluate the security gate for a pipeline run; returns allow or deny with reasons.
POST/api/v2/ci/{scan_id}/break-glassAudited override of a gate by an authorised principal.

Further endpoints cover cloud accounts and posture, DAST, IAST, integrations, ticketing, governance policies and the policy builder, frameworks and GRC, the auditor portal, evidence trail, risk graph, VEX and reports. An OpenAPI document for your deployment is available on request.

Errors

  • 401 — missing or invalid credentials.
  • 403 — authenticated, but not permitted for this organisation or action.
  • 422 — validation failed; the body names the offending field. Unknown fields are rejected.
  • 429 — rate-limited; back off and retry.
  • 500 — unexpected server error, returned with a correlation id only.

Business errors return a structured body with a stable error_code, a category, a readable message, an actionable user_hint, a correlation_id and a retryable flag.

Contacting support? Include the correlation_id from the response; it lets us trace the request end to end.

Rate limits and quotas

Per-organisation quotas apply to write operations, and pull-request comment posting is rate-limited per organisation. A rate-limited request returns 429 — back off and retry. Contact us if your workload needs higher limits.

Pagination

The findings list takes limit (1–200, default 50) and a cursor. Each response carries next_cursor while more rows exist; pass it back unchanged to fetch the next page. Cursors are bound to your organisation. Offset paging is not supported.

curl -s "https://app.securityvault.io/api/v2/findings?limit=200&severity=critical" \
  -H "Authorization: Bearer $TOKEN" -H "X-Organization-ID: $ORG_ID"

Hostnames

Every endpoint is served from one hostname — app.securityvault.io, or your own host when self-hosted. Clients do not need to route different calls to different hosts.

Next steps

← PreviousCLI reference