Trigger a Whitebox Scan

curl --request POST \
  --url https://api.example.com/scans

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/scans",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/scans"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/scans")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

POST

scans

Trigger a Whitebox Scan

curl --request POST \
  --url https://api.example.com/scans

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/scans",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/scans"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/scans")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

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

Create a cost estimation with POST /cost-estimations.
Wait until the estimation reaches completed or partial status and has a positive total_credits value.
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.
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

Field	Type	Required	Description
`cost_estimation_id`	UUID	Yes	ID of a completed or partial cost estimation with a positive `total_credits` value.
`repos`	object[]	Yes	At least one repository. The first is the primary target; additional entries are scanned as related repositories.
`target_urls`	string[]	No	Public live URLs to include in the assessment, such as staging or production URLs. Private and internal network URLs are rejected.
`auth_instructions`	string	No	Credentials or steps Hacktron should use to authenticate. Max 2000 chars.
`custom_context`	string	No	Additional scope, focus areas, exclusions, or testing notes. Max 2000 chars.
`context_document_ids`	UUID[]	No	IDs of context documents to attach to the scan.

Repo object

Field	Type	Required	Description
`url`	string	Yes	HTTPS URL of the repository. Must match a repository in the cost estimation.
`branch`	string	Yes	Branch to scan. Must match the branch used in the cost estimation.
`source`	enum	No	`connected`, `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"
}

Field	Type	Description
`id`	UUID	Scan UUID. Use this to fetch status, details, and findings.
`task_id`	string	Internal task identifier (also visible in the dashboard).
`status`	string	Always `pending` at creation time.
`message`	string	Status 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

Poll GET /scans/{id}/status until status is completed.
Fetch findings with GET /scans/{id}/findings or export them with GET /scans/{id}/findings/export.

Getting started

Cost Estimations

Scans

Findings

Trigger a Whitebox Scan

Prerequisites

Request

Body

Repo object

Response

Errors

Next steps

​Prerequisites

​Request

​Body

​Repo object

​Response

​Errors

​Next steps

Prerequisites

Request

Body

Repo object

Response

Errors

Next steps