Docs/Build/API reference

API reference.

JSON over HTTPS under /api/v2. Requests are validated with strict models — unknown fields are rejected, lengths are capped — and every tenant-scoped call carries the organisation header.

Base path /api/v2Auth Bearer JWT (RS256)Tenant X-Organization-IDSpec OpenAPI 3.1 (per deployment)Updated September 2026

Authentication

Interactive sessions receive a 15-minute RS256 access token and an httpOnly refresh cookie. CLI and CI clients obtain tokens through the OAuth 2.0 device flow (/api/v2/auth/device/code, /approve, /token) or a pipeline OIDC exchange (POST /api/v2/ci/pipeline/token-oidc). Every tenant-scoped request carries the organisation id; the server resolves the acting tenant from the verified session and this header, never from a caller-controlled query parameter.

Authorization: Bearer <jwt>
X-Organization-ID: 6f0c…b2e1
Content-Type: application/json

Core endpoints

Method	Path	Description
POST	`/api/v2/scans`	Create a scan for a repository, image or other target. Tools optional; omitted → auto plan.
GET	`/api/v2/scans/{scan_id}`	Scan status, per-tool outcomes, deadlines.
GET	`/api/v2/scans/{scan_id}/sbom/cyclonedx`	CycloneDX SBOM produced by the scan.
GET	`/api/v2/scan-requests/{id}/timeline`	Fan-out progress and state transitions for a multi-target request.
GET	`/api/v2/findings`	List findings with severity, status and entity filters; cursor pagination.
GET	`/api/v2/findings/{id}/detail`	Finding with typed evidence (code span, dataflow path, dependency path, config path, request trace, exploit proof, artifact hash).
GET	`/api/v2/findings/{id}/lineage`	Lineage view: satisfied hops with provenance, missing hops with reason, conflicts.
POST	`/api/v2/findings/{id}/disposition`	Human-only verdict with a mandatory reason code from `/api/v2/disposition/reason-codes`.
POST	`/api/v2/findings/{id}/verify-fixed`	Request re-verification of a fix.
POST	`/api/v2/findings/{id}/fix-pr`	Open an advisory fix pull request from a remediation template.
GET	`/api/v2/sca/dependencies`	Dependencies with reachability hints and licences.
POST	`/api/v2/sca/sboms/upload`	Upload an SBOM for a project version.
GET	`/api/v2/images`	Images by registry with per-digest results and running workloads.
POST	`/api/v2/images/{id}/scan`	Scan an image digest.
GET	`/api/v2/repositories/repos/{id}/overview`	Repository coverage, last scans, settings.
POST	`/api/v2/ci/gate/evaluate`	Evaluate the security gate for a pipeline run; returns allow/deny with reasons.
POST	`/api/v2/ci/{scan_id}/break-glass`	Audited override of a gate by an authorised principal.
POST	`/api/v2/scans/kubernetes`	Scan a registered, trusted execution cluster marked as a scan target.
POST	`/api/v2/policy/check`	Policy check for the current project; used by `esos policy check`.

Further routers cover cloud accounts and CNAPP posture, DAST, IAST, integrations, ticketing, governance policies and the policy builder, frameworks and GRC, the auditor portal, evidence trail, risk graph, ontology cases, VEX and reports. The full OpenAPI document is served per deployment when enabled by the operator.

Errors

Validation errors return 422 with the offending field; unknown fields are rejected (extra="forbid"). Authentication failures are 401, authorisation failures 403. Business errors return a structured body with a stable error_code, a category (network, auth, config, timeout), a user-visible message, an actionable hint, a correlation_id and a retryable flag. Infrastructure errors are 500 with the correlation id only.

A generic auth error with no detail is a crash, not a rejection. Report the correlation id.

Rate limits and quotas

Per-organisation API quotas apply on the write plane; PR comment posting is bucketed per organisation (default 50 per minute) and every attempt is recorded as posted, rate-limited or failed. Scanner callbacks are capped at 64 MiB per request body.

Pagination

List endpoints accept limit and a cursor; responses carry next_cursor when more rows exist. Use the cursor rather than an offset — large findings lists are backed by a read-model cache.

Traffic planes

The same routes are served from role-specific deployments: reads from api-read, mutations from api-write, scanner and webhook callbacks from api-callback, server-sent events from api-stream, cross-tenant administration from api-admin. A single hostname fronts them; the split is an operational property, not something clients need to route around.