Every endpoint under /api/v1

REST API

Everything under /api/v1 requires the X-API-Key header. /health is public; /api/v1/slack/actions authenticates by Slack signature instead. /mcp serves the same data to agents over Model Context Protocol, behind the same key — see mcp.md.

A request may also carry X-Session-Token, which is how the console says which person is asking. It is checked against the database, and a stale one is refused with 401 and {"code":"session_required"} rather than falling back to key-only access. A request without it — the CLI, an agent — is a machine client and the key is enough. See authentication.md.

Anything that outlives a request is queued rather than run: those endpoints answer 202 with a jobId, refuse a second concurrent run with 409, and report progress on a GET at the same path. See queues.md.

curl -H "X-API-Key: $API_KEY" http://localhost:3000/api/v1/vulnerabilities
curl -H "X-API-Key: $API_KEY" "http://localhost:3000/api/v1/vulnerabilities?severity=CRITICAL"
curl -H "X-API-Key: $API_KEY" http://localhost:3000/api/v1/stats

curl -X PATCH -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"status":"ACKNOWLEDGED","changedBy":"security-team"}' \
  http://localhost:3000/api/v1/vulnerabilities/CVE-2024-0001/status

Batch actions

A selection made in the console arrives as one call. Two of them, because they answer at different speeds.

Status is synchronous, and always 200 — never 400 because one CVE in the selection could not move. A selection taken off a table will contain rows that are already resolved or that somebody acknowledged a second ago, and failing the whole call over those means ticking boxes one at a time to find out which. Each CVE is reported with its own outcome instead.

curl -X PATCH -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"cveIds":["CVE-2024-0001","CVE-2024-0002"],"status":"ACKNOWLEDGED","changedBy":"security-team"}' \
  http://localhost:3000/api/v1/vulnerabilities/batch/status

{
  "requested": 2, "changed": 1, "skipped": 1,
  "changedIds": ["CVE-2024-0001"],
  "results": [
    { "cveId": "CVE-2024-0001", "ok": true, "status": "ACKNOWLEDGED" },
    { "cveId": "CVE-2024-0002", "ok": false, "error": "Invalid transition: RESOLVED → ACKNOWLEDGED" }
  ],
  "mitigation": { "accepted": true, "jobId": "…", "queued": 1 }
}

mitigation is there because acknowledging one CVE writes a mitigation guide, which is a model call. Fifty of them is not something a request can do, so the batch queues them and ends up where the single-CVE route ends up. It is null for a resolve, and carries a reason instead of a jobId when no model is configured — the status change still happened either way.

Text is a job. POST takes the same cveIds, plus kind (explanation, the default, or mitigation) and force. Without force a CVE that already has text is skipped, since the usual reason to run this is to fill in what was collected before a model was configured. A batch with no model configured is refused with 400 rather than queued to fail on every row.

curl -X POST -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"cveIds":["CVE-2024-0001"],"force":false}' \
  http://localhost:3000/api/v1/vulnerabilities/batch/explain

curl -H "X-API-Key: $API_KEY" http://localhost:3000/api/v1/vulnerabilities/batch/explain

DELETE cancels whatever is queued or active, and is the way out of "queued, and nothing is happening": a worker killed mid-batch leaves its job active until the expiry window passes — fifteen minutes — and a singleton queue holds everything behind it until then. pg-boss cannot tell a dead worker from a slow one, so it waits the window out.

The GET reports { running, jobId, progress, lastRun } like every other job, with progress counting done, written, skipped and failed and naming the CVE in hand. Failures are listed per CVE, capped at 20 with errorsTruncated set when there were more.

Both cap a selection at 200 CVEs and refuse a larger one with 400. A console page holds fifty; the cap is there so a scripted caller cannot hand the worker a job that outlives its own expiry window. The same CVE sent twice counts once.