REST API Reference v2.1 -- Scans
POST /scans
Creates a new vulnerability scan. Requires scans:write scope. Request body: {"target": "https://example.com", "scan_type": "full|quick|api|dependency", "config": {"follow_redirects": true, "max_depth": 5, "excluded_paths": ["/health", "/metrics"], "authentication": {"type": "bearer", "token": "..."}}}. The scan_type field determines which scanners are activated: full runs SAST, SCA, and DAST; quick runs only SCA and high-confidence SAST rules; api tests API endpoints against OpenAPI specifications; dependency scans only third-party dependencies.
Response: {"id": "scan_abc123", "status": "queued", "target": "https://example.com", "scan_type": "full", "created_at": "2025-03-28T10:00:00Z", "estimated_duration_seconds": 300}. Scans are processed asynchronously. Poll the scan status via GET /scans/:id or register a webhook for scan.completed events.
GET /scans/:id
Returns the current status and metadata of a scan. Status transitions: queued -> running -> completed or failed. The response includes progress percentage, findings count by severity, and any errors encountered during scanning.
Response for a completed scan: {"id": "scan_abc123", "status": "completed", "target": "https://example.com", "scan_type": "full", "started_at": "2025-03-28T10:00:15Z", "completed_at": "2025-03-28T10:05:42Z", "summary": {"critical": 2, "high": 5, "medium": 12, "low": 23, "info": 8}, "sbom_id": "sbom_xyz789"}. The sbom_id field links to the Software Bill of Materials generated during the scan.
GET /scans/:id/findings
Returns paginated findings for a completed scan. Each finding includes the vulnerability identifier (CVE or internal rule ID), severity, CVSS and EPSS scores, affected component, location in the codebase, and remediation guidance.
Query parameters: severity (critical, high, medium, low, info), component (filter by affected component name), has_fix (boolean, filter to findings with available fixes), sort (severity, epss_score, cvss_score), page and limit. Example response: {"data": [{"id": "finding_001", "rule_id": "CVE-2025-1234", "severity": "critical", "cvss_score": 9.8, "epss_score": 0.87, "component": "lodash@4.17.20", "location": "package.json", "title": "Prototype Pollution in lodash", "fix_version": "4.17.21", "description": "..."}]}.
All external references have been reviewed by our editorial team.