Skip to main content
POST
Trigger a Whitebox Scan
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

Body

Repo object

POST /scans accepts the REST API repo shape shown above. Cost estimations use repo_url; scan creation uses url.

Response

201 Created

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