---
title: Update a pentest draft
description: Change a pentest that hasn't started.
url: https://www.hacktron.ai/docs/api/pentests/update-pentest
---

# Update a pentest draft

Updates a pentest draft. Fields in the request replace their saved values, and fields you leave out keep their current values. You can't change a pentest after it starts. You need the member role or above.

- `repos` replaces the saved repository list and must contain at least one entry. Changing it clears the estimate.
- `login_targets` replaces the full list. Send `[]` to remove all login targets. Sending the same site and login instructions keeps a successful login check. Changing either resets `login_check` to `unverified` until you check again.
- To fix a login that failed its check, send the site again with new `login_instructions`, then call [`POST /pentests/{id}/login-checks`](/docs/api/pentests/check-pentest-logins).
- To switch a draft from signed-in testing to testing without a login, or back, clear the other list in the same request, for example `"login_targets": []` with your `target_urls`.

After changing the draft, estimate it again with [`POST /pentests/{id}/estimate`](/docs/api/pentests/estimate-pentest). [`POST /pentests/{id}/start`](/docs/api/pentests/start-pentest) rejects a credit total that doesn't match the current estimate.

## Request

`PATCH /pentests/{id}`

Send an [API key](/docs/api/authentication) with the `write` scope in the `X-Api-Key` header.

:::examples

```bash title="Request" wrap=false
curl -X PATCH "https://api.hacktron.ai/v1/pentests/<id>" \
  -H "X-Api-Key: $HACKTRON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "login_targets": [],
  "target_urls": ["https://staging.acme.dev"]
}'
```

```json title="Response 200 OK" showLineNumbers=false wrap=false
{
  "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 | Type | Description |
| --- | --- | --- |
| `id` | string, required | |

### Body

A required `application/json` body.

| Field | Type | Description |
| --- | --- | --- |
| `target_urls` | array of string | Target URLs (pentest only). |
| `custom_context` | string | Custom context (pentest only). |
| `application_id` | string | iva application this scan targets (group of repos). |
| `login_targets` | array of object | Deployed sites to test signed in, each with how to sign in. On update the list replaces the saved one, and [] removes them. A pentest tests live sites either all signed in or all without a login (target_urls). Check each login with POST /pentests/{id}/login-checks before starting. At most 10 items. |
| `login_targets[].site` | string, required | A deployed copy of the app to test signed in, e.g. https://staging.acme.dev. At most 2048 characters. |
| `login_targets[].login_instructions` | string, required | How to sign in: the login page, username, password and any steps. Stored encrypted and never returned. At most 2000 characters. |
| `repos` | array of object | Repositories or uploaded archives to test, replacing the saved ones. Changing them clears the estimate, so estimate again before starting. At least 1 item. |
| When `source` is `connected` | | |
| `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, required | Always `connected`. |
| `repos[].url` | string, required | Repository URL. |
| `repos[].branch` | string, required | 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[].github_installation_id` | number | GitHub App installation id. Omitted for PAT-based connections (e.g. GitHub Enterprise), where the installation is resolved from the repository URL and the organization instead. |
| When `source` is `public` | | |
| `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, required | Always `public`. |
| `repos[].url` | string, required | Repository URL. |
| `repos[].branch` | string, required | 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`. |
| When `source` is `upload` | | |
| `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, required | Always `upload`. |
| `repos[].archive_id` | string, required | Scan archive ID. |

## Responses

### 200 OK

| Field | Type | 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 | |
