Skip to main content
POST
/
scans
Trigger a Whitebox Scan
curl --request POST \
  --url https://api.example.com/scans
Starts a Whitebox Scan against the repositories attached to a completed or partial 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.
  2. Wait until the estimation reaches completed or partial status and has a positive total_credits value.
  3. Submit the same repositories and branches that were included in the estimation. Hacktron rejects scans whose repo, archive, or branch does not match the estimate.
  4. Ensure your organization has enough Whitebox Scan credits. Credits are visible in Credits and billing in the dashboard. Insufficient credits return 402 Payment Required.
A cost estimation can only be claimed by one started scan. If you need to change repositories, archives, or branches, create a new estimate first.

​
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 or partial cost estimation with a positive total_credits value.
reposobject[]YesAt least one repository. The first is the primary target; additional entries are scanned as related repositories.
target_urlsstring[]NoPublic live URLs to include in the assessment, such as staging or production URLs. Private and internal network URLs are rejected.
auth_instructionsstringNoCredentials or steps Hacktron should use to authenticate. Max 2000 chars.
custom_contextstringNoAdditional scope, focus areas, exclusions, or testing notes. Max 2000 chars.
context_document_idsUUID[]NoIDs of context documents to attach to the scan.

​
Repo object

FieldTypeRequiredDescription
urlstringYesHTTPS URL of the repository. Must match a repository in the cost estimation.
branchstringYesBranch to scan. Must match the branch used in the cost estimation.
sourceenumNoconnected, public, or upload. Defaults to connected.
POST /scans accepts the REST API repo shape shown above. Cost estimations use repo_url; scan creation uses url.

​
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 fields, cost estimate not ready, zero-credit estimate, repo not included in the estimate, branch mismatch, private target URL, or a scan that already claimed the estimate.
  • 401 / 403 — authentication or scope failure.
  • 402 — insufficient Whitebox Scan credits. Top up from Credits and billing in the dashboard.
  • 404 — cost estimation not found or not visible to your organization.

​
Next steps