Cloud API Reference

The HAVOC Cloud REST API allows you to programmatically manage scans, findings, and repositories. API access requires a Team, Business, or Enterprise plan.

Base URL: https://api.havoc.cloud/v1
All requests must use HTTPS. The API returns JSON.

Authentication

All API requests require a Bearer token in the Authorization header:

Authorization: Bearer hvk_your_api_key_here

Generate API keys in your HAVOC Cloud dashboard under Settings → API Keys. Keys are scoped to a team and inherit team permissions.

Token scopes

Scope	Description
read:scans	List and view scan results
write:scans	Trigger new scans
read:findings	List and view findings
write:findings	Update finding status (dismiss, accept)
read:repos	List connected repositories
admin	Full access including team management

Scans

List scans

GET/scans

Returns a paginated list of scans for the authenticated team.

Query parameters

Parameter	Type	Description
repository_id	string	Filter by repository
branch	string	Filter by branch name
status	string	Filter by status: pending, running, complete, failed
page	integer	Page number (default: 1)
per_page	integer	Results per page (default: 25, max: 100)

curl -H "Authorization: Bearer hvk_..." \
  "https://api.havoc.cloud/v1/scans?repository_id=repo_abc123&per_page=10"

Get scan

GET/scans/{scan_id}

Returns a single scan with full results.

{
  "id": "scan_01J9X4KMPQ3T5N8ZR7Y2CWBD6F",
  "repository_id": "repo_abc123",
  "branch": "feature/bulk-transactions",
  "commit": "a3f8b2c",
  "status": "complete",
  "started_at": "2026-03-05T04:12:33Z",
  "completed_at": "2026-03-05T04:12:51Z",
  "scan_type": "diff",
  "coverage": {
    "percentage": 89.8,
    "covered": 132,
    "total": 147,
    "delta": -2.4
  },
  "finding_counts": {
    "critical": 0,
    "high": 1,
    "medium": 1,
    "low": 1,
    "info": 0,
    "total": 3
  }
}

Trigger scan

POST/scans

Triggers a new cloud scan on a connected repository.

The scan_type field accepts "full" or "diff".

# Request body (JSON)
{
  "repository_id": "repo_abc123",
  "branch": "main",
  "scan_type": "full"
}

Findings

List findings

GET/findings

Parameter	Type	Description
scan_id	string	Filter by scan
severity	string	Filter by severity
status	string	open, dismissed, fixed
rule	string	Filter by analyzer rule ID

Update finding status

PUT/findings/{finding_id}

# Request
{
  "status": "dismissed",
  "reason": "False positive — this endpoint is protected by middleware"
}

Repositories

List repositories

GET/repositories

Returns all repositories connected to the authenticated team.

Get repository stats

GET/repositories/{repo_id}/stats

Returns coverage trend, finding history, and grade history for a repository.

Error Codes

Status	Code	Description
401	unauthorized	Missing or invalid API token
403	forbidden	Token lacks required scope
404	not_found	Resource not found or not accessible
422	validation_error	Invalid request body (details in errors field)
429	rate_limited	Too many requests. Retry-After header included.
500	server_error	Internal error. Contact support.

Rate limits

Plan	Requests/minute	Scans/day
Team	60	100
Business	300	unlimited
Enterprise	custom	unlimited