Skip to main content
POST
/
scans
Trigger a pentest scan
curl --request POST \
  --url https://api.example.com/scans
Starts a full pentest scan against the repositories attached to a completed cost estimation. Scans run asynchronously; the endpoint returns immediately with a scan id for polling.
Scope required: write

​
Prerequisites

  1. Create a cost estimation with POST /cost-estimations and wait for it to reach completed status.
  2. Ensure your organization has enough pentest credits (visible in Billing in the dashboard). Insufficient credits return 402 Payment Required.

​
Request

curl -X POST https://api.hacktron.ai/v1/scans \
  -H "X-Api-Key: $HACKTRON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cost_estimation_id": "b4f5c6a1-2d3e-4f56-9a8b-0c1d2e3f4a5b",
    "repos": [
      {
        "url": "https://github.com/acme/backend",
        "branch": "main",
        "source": "connected"
      }
    ],
    "target_urls": ["https://staging.acme.com"],
    "auth_instructions": "Use test account test@acme.com / hunter2",
    "custom_context": "Focus on the payment flow under /api/v1/checkout"
  }'

​
Body

FieldTypeRequiredDescription
cost_estimation_idUUIDYesID of a completed cost estimation. The first repo in repos must match the estimation.
reposobject[]YesAt least one repository. The first is the primary target; any additional entries are scanned as related repositories.
target_urlsstring[]NoLive URLs to include in the pentest (for example a staging environment).
auth_instructionsstringNoCredentials or steps the scanner should follow to authenticate. Max 2000 chars.
custom_contextstringNoAdditional context: scope, areas to emphasise, exclusions. Max 2000 chars.
context_document_idsUUID[]NoIDs of context documents to attach to the scan.

​
Repo object

FieldTypeRequiredDescription
urlstringYesHTTPS URL of the repository.
branchstringYesBranch to scan.
sourceenumNoconnected, public, or upload. Defaults to connected.

​
Response

201 Created 
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "task_id": "web_scan_1712345678",
  "status": "pending",
  "message": "Scan started"
}
FieldTypeDescription
idUUIDScan UUID. Use this to fetch status, details, and findings.
task_idstringInternal task identifier (also visible in the dashboard).
statusstringAlways pending at creation time.
messagestringStatus message suitable for display.

​
Errors

  • 400 — missing repos, invalid cost_estimation_id, or validation failure.
  • 401 / 403 — authentication or scope failure.
  • 402 — insufficient pentest credits. Top up from the Billing page in the dashboard.

​
Next steps