Scans API

Create, manage, and monitor vulnerability scans programmatically.

Endpoints

Method	Endpoint	Description
GET	/api/v1/scans	List all scans
POST	/api/v1/scans	Create a new scan
GET	/api/v1/scans/{id}	Get scan details
DELETE	/api/v1/scans/{id}	Cancel/delete scan
GET	/api/v1/scans/{id}/findings	Get scan findings

List Scans

Retrieve all scans for your organization.

GET /api/v1/scans

Query Parameters

Parameter	Type	Description
page	integer	Page number (default: 1)
per_page	integer	Items per page (default: 20, max: 100)
status	string	Filter by status: pending, running, completed, failed
target	string	Filter by target domain
from_date	string	Filter scans after date (ISO 8601)
to_date	string	Filter scans before date (ISO 8601)

Response

{
  "items": [
    {
      "id": "scan_abc123",
      "target": "example.com",
      "scan_type": "full",
      "status": "completed",
      "progress": 100,
      "phase": "complete",
      "created_at": "2025-12-21T10:00:00Z",
      "completed_at": "2025-12-21T10:45:00Z",
      "vulnerabilities_found": 12,
      "critical_count": 1,
      "high_count": 3,
      "medium_count": 5,
      "low_count": 3
    }
  ],
  "total": 45,
  "page": 1,
  "per_page": 20,
  "pages": 3
}

Create Scan

Start a new vulnerability scan.

POST /api/v1/scans
Content-Type: application/json

Request Body

{
  "target": "example.com",
  "scan_type": "full",
  "frameworks": ["soc2", "pci-dss"],
  "ports": "1-1000",
  "authorized": true
}

Parameters

Field	Type	Required	Description
target	string	Yes	Domain, IP, or CIDR range
scan_type	string	No	quick, full, or compliance (default: full)
frameworks	array	No	Compliance frameworks to check
ports	string	No	Port range (default: common ports)
authorized	boolean	Yes	Attestation of scan authorization

Scan Types

Type	Duration	Coverage
quick	5-10 min	Top vulnerabilities, common ports
full	30-60 min	All 11 phases, comprehensive coverage
compliance	15-30 min	Framework-specific checks

Response

{
  "id": "scan_xyz789",
  "target": "example.com",
  "scan_type": "full",
  "status": "pending",
  "created_at": "2025-12-21T14:00:00Z",
  "estimated_duration": 2700
}

Get Scan Details

Retrieve details for a specific scan.

GET /api/v1/scans/{scan_id}

Response

{
  "id": "scan_abc123",
  "target": "example.com",
  "scan_type": "full",
  "status": "running",
  "progress": 45,
  "phase": "vulnerability_scanning",
  "current_tool": "nuclei",
  "created_at": "2025-12-21T10:00:00Z",
  "started_at": "2025-12-21T10:01:00Z",
  "phases_completed": [
    "discovery",
    "enumeration"
  ],
  "phases_remaining": [
    "vulnerability_scanning",
    "web_analysis",
    "cloud_analysis",
    "threat_intelligence",
    "correlation",
    "ai_analysis",
    "remediation_planning",
    "reporting"
  ]
}

Cancel Scan

Stop a running scan.

DELETE /api/v1/scans/{scan_id}

Response

{
  "id": "scan_abc123",
  "status": "cancelled",
  "message": "Scan cancelled successfully"
}

Get Scan Findings

Retrieve vulnerabilities found during a scan.

GET /api/v1/scans/{scan_id}/findings

Query Parameters

Parameter	Type	Description
severity	string	Filter: critical, high, medium, low, info
status	string	Filter: open, in_progress, resolved, false_positive

Response

{
  "items": [
    {
      "id": "finding_123",
      "title": "SQL Injection in Login Form",
      "severity": "critical",
      "cvss_score": 9.8,
      "status": "open",
      "tool": "sqlmap",
      "affected_component": "https://example.com/login",
      "description": "...",
      "remediation": "...",
      "cve_ids": ["CVE-2024-1234"],
      "detected_at": "2025-12-21T10:30:00Z"
    }
  ],
  "total": 12
}

Scan Quota

Check remaining scan quota.

GET /api/v1/scans/quota

Response

{
  "plan": "professional",
  "monthly_limit": 150,
  "used_this_month": 45,
  "remaining": 105,
  "resets_at": "2026-01-01T00:00:00Z"
}

Scheduled Scans

Professional and Enterprise

Scheduled scans are available on Professional and Enterprise plans.

Create Schedule

POST /api/v1/scans/schedules
Content-Type: application/json

{
  "target": "example.com",
  "scan_type": "full",
  "frequency": "weekly",
  "day_of_week": 1,
  "hour": 2,
  "timezone": "UTC"
}

List Schedules

GET /api/v1/scans/schedules

Delete Schedule

DELETE /api/v1/scans/schedules/{schedule_id}

Webhooks for Scans

Register for scan event notifications:

POST /api/v1/webhooks
Content-Type: application/json

{
  "url": "https://your-server.com/webhook",
  "events": [
    "scan.started",
    "scan.completed",
    "scan.failed",
    "vulnerability.critical"
  ]
}

Rate Limits

Plan	Concurrent Scans	Scans/Month
Startup	1	25
Professional	3	150
Enterprise	Unlimited	Unlimited