Start a pentest

1 min

, , , , ,

Starts a pentest draft that has a completed estimate. The confirmed credits are deducted when the pentest starts. Only organisation admins can call it.

Set expected_credits to the estimate’s total_credits, plus triage_fee_credits if triage is required or you set triage_enabled. If the current cost differs from this total, the endpoint returns 409 without spending credits. If the organisation has insufficient credits, it returns 402.
Every login target needs a login check that passed within the last hour. Run the checks with POST /pentests/{id}/login-checks.

After it starts, follow the pentest with GET /scans/{id}/status using the same scan_id, read its results with GET /scans/{id}/findings, or stop it with POST /scans/{id}/stop.

Request

POST /pentests/{id}/start

Send an API key with the write scope in the X-Api-Key header.

curl -X POST "https://api.hacktron.ai/v1/pentests/<id>/start" \
  -H "X-Api-Key: $HACKTRON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "expected_credits": 1
}'

{
  "scan_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "pending",
  "repos": [
    {
      "include_paths": [
        "services/gateway/**"
      ],
      "exclude_paths": [
        "**/tests/**",
        "vendor/",
        "*.md"
      ],
      "source": "connected",
      "provider": "github",
      "url": "https://github.com/owner/repo",
      "branch": "string",
      "ref_type": "branch",
      "archive_id": "string",
      "github_installation_id": 0
    }
  ],
  "target_urls": [
    "string"
  ],
  "login_targets": [
    {
      "site": "string",
      "login_check": "unverified",
      "failure_reason": "string"
    }
  ],
  "custom_context": "string",
  "application_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "cost_estimation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "triage_enabled": true,
  "credits_used": 0
}

Path parameters

Parameter	Description
`id` string, required

Body

A required application/json body.

Field	Description
`expected_credits` integer, required	The total the user confirmed: the estimate's total_credits, plus triage_fee_credits when triage is required or opted in. At least 1.
`triage_enabled` boolean	Opt in to human triage of findings when it is not already required.

Responses

200 OK

Field	Description
`scan_id` string (uuid), required	Stable pentest id; task_id changes when it starts.
`status` string, required	One of `pending`, `running`, `completed`, `failed`, `stopped`, `cancelled`, `skipped`, `pending_verification`, `pending_triage`, `draft`, `estimating`, or `estimated`.
`repos` array of object, required
`repos[].include_paths` array of string	Whitebox scope: gitignore-style globs (relative to the repo root) that narrow the scan to matching paths. Empty means the whole repository.
`repos[].exclude_paths` array of string	Whitebox scope: gitignore-style globs removed from the scan after include_paths is applied; use `*.md` to drop a file type.
`repos[].source` string	One of `connected`, `public`, or `upload`.
`repos[].provider` string, read-only	Resolved by the server at scan start; ignored on input. One of `github`, `gitlab`, `bitbucket`, or `azure`.
`repos[].url` string	Repository URL.
`repos[].branch` string	Branch name, tag name, or commit SHA.
`repos[].ref_type` string	How `branch` was selected (UI hint for draft re-use). One of `branch`, `tag`, or `sha`.
`repos[].archive_id` string	Scan archive ID.
`repos[].github_installation_id` number	GitHub App installation ID (connected repos only).
`target_urls` array of string, required
`login_targets` array of object, required
`login_targets[].site` string, required
`login_targets[].login_check` string, required	Whether Hacktron could sign in with the login the site has now. A pass lasts an hour, and changing the site or login makes it unverified. One of `unverified`, `pending`, `running`, `succeeded`, `failed`, `cancelled`, or `expired`.
`login_targets[].failure_reason` string, required, nullable	Why the check failed, without credentials.
`custom_context` string, required, nullable
`application_id` string (uuid), required, nullable
`cost_estimation_id` string (uuid), required, nullable
`triage_enabled` boolean, required, nullable
`credits_used` number, required, nullable

400 Bad Request

A login target has no passing login check from the last hour.

402 Payment Required

Insufficient credits.

409 Conflict

expected_credits no longer matches the total; read the estimate again and confirm the new total.