> ## Documentation Index
> Fetch the complete documentation index at: https://hacktronai-changelog-e1a164be.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Trigger a Whitebox Scan

> Start a Whitebox Scan against one or more repositories.

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.

<Info>
  **Scope required**: `write`
</Info>

## Prerequisites

1. Create a cost estimation with [`POST /cost-estimations`](/api-reference/cost-estimations/create-cost-estimation).
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](/white-box-pentest/billing) in the
   dashboard. Insufficient credits return `402 Payment Required`.

<Warning>
  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.
</Warning>

## Request

```bash theme={null}
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`.                 |

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

## Response

`201 Created`

```json theme={null}
{
  "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](/white-box-pentest/billing) in the dashboard.
* `404` — cost estimation not found or not visible to your organization.

## Next steps

* Poll [`GET /scans/{id}/status`](/api-reference/scans/get-scan-status) until status is `completed`.
* Fetch findings with [`GET /scans/{id}/findings`](/api-reference/scans/list-scan-findings) or export them with [`GET /scans/{id}/findings/export`](/api-reference/scans/export-scan-findings).