Scanner API Documentation

REST API for submitting and retrieving scans. All endpoints return JSON and require Bearer token authentication.

Authentication

Bearer Token

All API requests must include an Authorization header with a valid Bearer token.

Tokens can be created from the admin settings panel or your user dashboard under API Keys.

Authorization: Bearer YOUR_API_TOKEN

Requests without a valid token receive a 401 Unauthorized response.

Rate Limiting

60 requests per minute

All /api/v1 endpoints are rate-limited to 60 requests per minute per IP address.

Rate limit status is returned in response headers:

Header	Description
`RateLimit-Limit`	Maximum requests allowed per window
`RateLimit-Remaining`	Remaining requests in current window
`RateLimit-Reset`	Seconds until the rate limit window resets

Exceeding the limit returns 429 Too Many Requests.

Error Handling

All errors return a JSON body with an error field describing what went wrong.

{
  "error": "Description of the error"
}

Status Code	Meaning
`400`	Bad Request - invalid or missing parameters
`401`	Unauthorized - missing or invalid API token
`404`	Not Found - resource does not exist
`409`	Conflict - scan already in progress for this target
`429`	Too Many Requests - rate limit or scan limit exceeded
`500`	Internal Server Error

Endpoints

Submit a New Scan

POST /api/v1/scan

Submit a new security scan for the specified target. The scan is added to the queue and processed asynchronously.

Body Parameter	Type	Required	Description
`target`	string	Required	The target to scan (IP address or hostname)
`domain`	string	Optional	Domain name for the scan. Defaults to the target value if omitted.

Response 201

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "queued",
  "reportUrl": "/report/a1b2c3d4-e5f6-7890-abcd-ef1234567890?key=abc123..."
}

Error Responses

400 Invalid target or domain
409 Scan already in progress for this target (response includes existingId)
429 Monthly scan limit reached or queue full

cURL Example

curl -X POST https://your-scanner-domain/api/v1/scan \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"target": "192.168.1.1", "domain": "example.com"}'

Get Scan Status

GET /api/v1/scan/:id

Retrieve the current status and results of a scan by its ID.

Path Parameter	Type	Description
`id`	string (UUID)	The scan ID returned when the scan was submitted

Response 200

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "target": "192.168.1.1",
  "domain": "example.com",
  "status": "complete",
  "grade": "B+",
  "gradeScore": 82,
  "reportUrl": "/report/a1b2c3d4-...?key=abc123...",
  "createdAt": "2026-04-03T12:00:00.000Z",
  "startedAt": "2026-04-03T12:00:05.000Z",
  "completedAt": "2026-04-03T12:02:30.000Z",
  "error": null,
  "summary": { /* scan summary object or null */ }
}

The status field will be one of: queued, running, complete, failed, cancelled.

The reportUrl is only populated when the scan is complete.

Error Responses

404 Scan not found

cURL Example

curl https://your-scanner-domain/api/v1/scan/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

List Scans

GET /api/v1/scans

Retrieve a paginated list of scans. Results are scoped to your team when using a user API token.

Query Parameter	Type	Default	Description
`limit`	integer	50	Number of results to return (max 100)
`offset`	integer	0	Number of results to skip for pagination
`target`	string	none	Filter scans by target (exact match)

Response 200

{
  "scans": [
    {
      "id": "a1b2c3d4-...",
      "target": "192.168.1.1",
      "domain": "example.com",
      "status": "complete",
      "grade": "B+",
      "created_at": "2026-04-03T12:00:00.000Z"
    }
  ],
  "total": 42,
  "limit": 50,
  "offset": 0
}

Error Responses

400 Invalid target filter value

cURL Example

# List first 10 scans
curl "https://your-scanner-domain/api/v1/scans?limit=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Filter by target
curl "https://your-scanner-domain/api/v1/scans?target=192.168.1.1" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Retest a Scan

POST /api/v1/scan/:id/retest

Create a new scan using the same target and domain as an existing scan. Useful for re-testing after remediation.

Path Parameter	Type	Description
`id`	string (UUID)	The ID of the original scan to retest

Response 201

{
  "id": "new-scan-uuid-...",
  "status": "queued",
  "reportUrl": "/report/new-scan-uuid-...?key=abc123..."
}

Error Responses

404 Original scan not found
429 Monthly scan limit reached

cURL Example

curl -X POST https://your-scanner-domain/api/v1/scan/a1b2c3d4-e5f6-7890-abcd-ef1234567890/retest \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Cancel a Scan

POST /api/v1/scan/:id/cancel

Cancel a scan that is currently queued or running. Scans that are already complete, failed, or cancelled cannot be cancelled.

Path Parameter	Type	Description
`id`	string (UUID)	The ID of the scan to cancel

Response 200

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "cancelled"
}

Error Responses

400 Cannot cancel a scan that is already complete, failed, or cancelled
404 Scan not found

cURL Example

curl -X POST https://your-scanner-domain/api/v1/scan/a1b2c3d4-e5f6-7890-abcd-ef1234567890/cancel \
  -H "Authorization: Bearer YOUR_API_TOKEN"