Scans

The Scans API lets you create, monitor, and manage security scans against your assets.

Create Scan

POST /api/scan/create

Request Body

Field Type Required Description
asset_id string Yes Target asset ID.
scan_type string Yes Type of scan to run.
options object No Scan-specific configuration options.
priority string No Scan priority: low, normal, high.
callback_url string No Webhook URL to notify on completion.

Scan Types

Type Description
full Comprehensive scan covering all checks.
quick Fast scan with critical and high-severity checks.
custom User-defined scan with selected check categories.
api_discovery API endpoint discovery and documentation analysis.
ssl TLS/SSL certificate and configuration analysis.
dns DNS configuration and security checks.
port TCP/UDP port scanning and service detection.

Example

curl -X POST "https://api.s4e.io/api/scan/create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "asset_id": "a-1001",
    "scan_type": "full",
    "options": {
      "depth": "deep",
      "include_subdomains": true,
      "categories": ["web_vuln", "ssl", "headers"]
    },
    "priority": "high"
  }'

Response (201 Created)

{
  "data": {
    "scan_id": "sc-44021",
    "asset_id": "a-1001",
    "scan_type": "full",
    "status": "queued",
    "priority": "high",
    "created_at": "2026-04-28T12:00:00Z",
    "estimated_duration_minutes": 15
  }
}

List Scans

GET /api/scans

Query Parameters

Parameter Type Default Description
status string all Filter: queued, running, completed, failed, cancelled.
asset_id string Filter by asset ID.
scan_type string Filter by scan type.
from string Start date (ISO 8601).
to string End date (ISO 8601).
page integer 1 Page number.
per_page integer 20 Results per page (max 100).

Example

curl -X GET "https://api.s4e.io/api/scans?status=completed&asset_id=a-1001&per_page=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Scan Details

GET /api/scan/{id}

curl -X GET "https://api.s4e.io/api/scan/sc-44021" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": {
    "scan_id": "sc-44021",
    "asset_id": "a-1001",
    "asset_name": "example.com",
    "scan_type": "full",
    "status": "completed",
    "priority": "high",
    "progress": 100,
    "finding_summary": {
      "critical": 1,
      "high": 2,
      "medium": 5,
      "low": 3,
      "info": 10
    },
    "started_at": "2026-04-28T12:00:30Z",
    "completed_at": "2026-04-28T12:14:22Z",
    "duration_seconds": 832,
    "created_at": "2026-04-28T12:00:00Z"
  }
}

Get Scan Status

GET /api/scan/{id}/status

Lightweight endpoint for polling scan progress:

curl -X GET "https://api.s4e.io/api/scan/sc-44021/status" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": {
    "scan_id": "sc-44021",
    "status": "running",
    "progress": 65,
    "current_phase": "web_vulnerability_checks",
    "eta_seconds": 290
  }
}

Scan States

State Description
queued Scan is waiting in the queue.
running Scan is actively executing.
completed Scan finished successfully.
failed Scan encountered an error.
cancelled Scan was manually cancelled.

Cancel Scan

POST /api/scan/{id}/cancel

Cancel a queued or running scan:

curl -X POST "https://api.s4e.io/api/scan/sc-44021/cancel" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": {
    "scan_id": "sc-44021",
    "status": "cancelled",
    "message": "Scan cancelled by user."
  }
}

Note

Cancelling a running scan stops further checks but preserves any findings already discovered. The partial results are accessible via the results endpoint.

Get Scan Results

GET /api/scan/{id}/results

Returns findings discovered during the scan:

curl -X GET "https://api.s4e.io/api/scan/sc-44021/results?severity=critical,high" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": [
    {
      "id": "f-91827",
      "title": "SQL Injection in /api/login",
      "severity": "critical",
      "cvss": 9.8,
      "status": "open",
      "description": "User input is passed directly to SQL query.",
      "remediation": "Use parameterized queries.",
      "discovered_at": "2026-04-28T12:05:00Z"
    }
  ],
  "meta": {
    "total": 3,
    "page": 1,
    "per_page": 20
  }
}

Field Reference

Field Type Description
scan_id string Unique scan identifier.
asset_id string Target asset identifier.
asset_name string Target asset name.
scan_type string Type of scan executed.
status string Current scan state.
priority string Scan priority level.
progress integer Completion percentage (0-100).
current_phase string Currently executing phase.
finding_summary object Finding counts by severity.
started_at string ISO 8601 scan start timestamp.
completed_at string ISO 8601 scan completion timestamp.
duration_seconds integer Total scan duration.
estimated_duration_minutes integer Estimated duration at creation.

Next Steps