Scans & Vulnerability Findings API
Trigger multi-engine scans, query running scan progress, and inspect verified vulnerability findings.
Scan Trigger & Status Lifecycle
Scans transition through states: QUEUED → RUNNING → COMPLETED (or FAILED). Never fake scan completion; poll the status endpoint or subscribe to webhooks.
Endpoints Reference (2)
POST/api/v1/scans/trigger
Permission: SCAN_TRIGGERTrigger a new multi-engine scan
Request Example (cURL)
curl -X POST "http://localhost:8000/api/v1/scans/trigger" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"project_id": "7f8b91a2-3c4d-5e6f-a7b8-c9d0e1f2a3b4"}'Response (201 Scan queued successfully)
{
"scan_id": "3e9b1102-fa42-491a-912a-0012948123ab",
"status": "QUEUED",
"created_at": "2026-11-17T00:30:00Z"
}GET/api/v1/scans/{scan_id}
Permission: SCAN_READRetrieve scan progress & executions
Parameters:
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| scan_id | path | UUID | Yes | Unique identifier of scan run |
Request Example (cURL)
curl -X GET "http://localhost:8000/api/v1/scans/3e9b1102-fa42-491a-912a-0012948123ab" \
-H "Authorization: Bearer YOUR_API_TOKEN"Response (200 Scan details and findings summary)
{
"id": "3e9b1102-fa42-491a-912a-0012948123ab",
"status": "COMPLETED",
"scanner_count": 3,
"finding_count": 2,
"findings": [
{
"id": "fnd_01",
"title": "SQL Injection in auth handler",
"severity": "CRITICAL"
}
]
}