> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hacktron.ai/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>

## 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).


## OpenAPI

````yaml POST /scans
openapi: 3.0.0
info:
  title: Hacktron REST API
  description: Public REST API for programmatic access to Hacktron
  version: '1.0'
  contact: {}
servers:
  - url: https://api.hacktron.ai/v1
security:
  - api-key: []
tags: []
paths:
  /scans:
    post:
      tags:
        - REST API - Scans
      summary: Trigger a pentest scan
      operationId: RestScanController_create
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RestCreateScanDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestCreateScanResponseDto'
        '402':
          description: Insufficient credits
components:
  schemas:
    RestCreateScanDto:
      type: object
      properties:
        cost_estimation_id:
          type: string
          description: Completed cost estimation UUID
        repos:
          description: Repositories to scan
          type: array
          items:
            $ref: '#/components/schemas/RestRepoDto'
        target_urls:
          description: Target URLs for pentest
          type: array
          items:
            type: string
        auth_instructions:
          type: string
          description: Authentication instructions for the target
          maxLength: 2000
        custom_context:
          type: string
          description: Custom context for the pentest
          maxLength: 2000
        context_document_ids:
          description: Context document UUIDs to include
          type: array
          items:
            type: string
      required:
        - cost_estimation_id
        - repos
    RestCreateScanResponseDto:
      type: object
      properties:
        id:
          type: string
        task_id:
          type: string
        status:
          type: string
        message:
          type: string
      required:
        - id
        - task_id
        - status
        - message
    RestRepoDto:
      type: object
      properties:
        url:
          type: string
          description: Repository URL
        branch:
          type: string
          description: Branch name
        source:
          type: string
          description: Repository source
          enum:
            - connected
            - public
            - upload
          default: connected
      required:
        - url
        - branch
  securitySchemes:
    api-key:
      type: apiKey
      in: header
      name: X-Api-Key

````