> ## Documentation Index
> Fetch the complete documentation index at: https://docs.app.strix.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Pentests

> Start, monitor, and download pentest results

export const ScarfPixel = () => <img referrerPolicy="no-referrer-when-downgrade" src="https://static.scarf.sh/a.png?x-pxid=831669b6-b4bd-42cb-8832-2122c03e1d5f" alt="" width="1" height="1" style={{
  position: "absolute",
  width: 0,
  height: 0,
  opacity: 0,
  pointerEvents: "none"
}} />;

<ScarfPixel />

## List pentests

Get pentests with optional filters and pagination.

```bash theme={null}
curl -X GET "https://app.strix.ai/api/v1/scans?limit=20" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>"
```

By default, the list does not include per-finding retest scans. To include them, pass `include_retests=true`.

**Required scope:** `scans:read`

## Verify a domain

Strix scans a domain only after you prove that you own the domain. Add the domain, then call the verify endpoint.

`POST /api/v1/domains` already checks ownership when you add the domain. The ownership checks share a deadline of four seconds. Read the `verified` field in the response. When `verified` is `false`, the `detail` field names the exact DNS TXT record to add and the retry command. The `next_steps` list gives one instruction per method. When Strix could not reach the domain over HTTPS, `reachable` is `false` and `next_steps` contains a reachability note.

```bash theme={null}
curl -X POST "https://app.strix.ai/api/v1/domains/<DOMAIN_ID>/verify" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>"
```

**Required scope:** `assets:write`

A `200` response does not mean success. Read the `status` field:

* `verified` — Strix confirmed ownership. The `verification_method` field names the method that passed. You can start scans against the domain.
* `pending` — Strix found no verification record yet. The `next_steps` list gives one instruction per method and the retry command. The `verification` object contains the DNS record, the file URL and content, and the meta tag.

Add one of the records, then call the endpoint again. DNS changes can take up to 24 hours to propagate. The CLI command is `strix cloud domains verify <DOMAIN_ID>`.

## Start a new pentest

Provide `domain_ids` for blackbox pentests or `repository_ids` for whitebox pentests.

```bash theme={null}
curl -X POST "https://app.strix.ai/api/v1/scans" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "domain_ids": ["<DOMAIN_ID>"],
    "concerns": "Check for authentication bypass vulnerabilities"
  }'
```

**Required scope:** `scans:write`

### Retry a launch safely

Creating a scan is billable and may outlive an interrupted HTTP response. Send
an `Idempotency-Key` when you call the API directly, and reuse the exact same
key and request body after a timeout, connection loss, `429`, retryable `409`,
or `5xx` response:

```bash theme={null}
curl -X POST "https://app.strix.ai/api/v1/scans" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Idempotency-Key: scan-$(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"domain_ids":["<DOMAIN_ID>"]}'
```

Keys are retained for 24 hours and are bound to the authenticated actor,
operation, and canonical request. Reusing a key for different input returns
`409 Conflict`. A completed retry is replayed only after Strix rechecks the
caller's current authorization. Use a new key only for a deliberate new scan.
The CLI generates a key automatically for `scans start` and `scans rerun`; use
`--idempotency-key` when an agent needs to persist the key across processes.

### Pentest depth

The optional `scan_tier` field sets the pentest depth. The depth controls how deep the pentest goes and which model quality it uses:

* `lite` — the full standard methodology at the lowest price (×0.3 credits).
* `standard` — balanced testing at a lower price (×0.75 credits).
* `ultra` — the deepest pentest and the default (×1, the standard price).

The multiplier applies to the pentest's credit price. The field is not applicable on self-hosted deployments, for organizations with raw model selection, and for organizations on the Enterprise plan.

Managed SaaS users normally choose only these three depth tiers; they do not
submit arbitrary provider/model identifiers. A small set of explicitly enabled
workspaces has a separate curated or raw model picker. Self-hosted deployments
can instead select a named `model_config_id` configured by an administrator.

```bash theme={null}
curl -X POST "https://app.strix.ai/api/v1/scans" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "domain_ids": ["<DOMAIN_ID>"],
    "scan_tier": "ultra"
  }'
```

## Get pentest detail

```bash theme={null}
curl -X GET "https://app.strix.ai/api/v1/scans/<SCAN_ID>" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>"
```

**Required scope:** `scans:read`

The response includes `repository_commits` for whitebox pentests: an object keyed by repository URL whose value is the full commit SHA the scan tested. It is `null` for blackbox pentests and for scans that ran before Strix recorded commits.

## Rerun a pentest

Run a previous pentest configuration again:

```bash theme={null}
curl -X POST "https://app.strix.ai/api/v1/scans/<SCAN_ID>/rerun" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Idempotency-Key: rerun-$(uuidgen)"
```

**Required scope:** `scans:write`

## Cancel a pentest

Cancel a pending or running pentest:

```bash theme={null}
curl -X POST "https://app.strix.ai/api/v1/scans/<SCAN_ID>/cancel" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>"
```

**Required scope:** `scans:write`

## Download report

Report downloads are available on the Enterprise plan. On Pro, each organization
can download one technical PDF report for free, and re-downloading that scan's
report stays free. The default report is a technical PDF; `retest`,
`attestation`, and `executive_summary` formats and DOCX output are also
available on Enterprise.

```bash theme={null}
curl -X GET "https://app.strix.ai/api/v1/scans/<SCAN_ID>/report" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -o report.pdf
```

**Required scope:** `scans:read`

The CLI can write the response directly to a file and add optional cover branding:

```bash theme={null}
strix cloud scans report <SCAN_ID> \
  --format executive_summary \
  --type docx \
  --provider-name "Acme Security" \
  --member-name-0 "Alex Doe" \
  --member-email-0 "alex@example.com" \
  --output report.docx
```

`--provider-name` accepts up to 80 characters. Add up to two preparers with
`--member-name-0` / `--member-email-0` and `--member-name-1` /
`--member-email-1`; each member field accepts up to 120 characters. Existing
output files are not replaced unless `--force` is explicit.

## Retest findings

List the retests recorded for a pentest:

```bash theme={null}
curl -X GET "https://app.strix.ai/api/v1/scans/<SCAN_ID>/retests" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>"
```

**Required scope:** `scans:read`

Run validation again for each finding in a pentest:

```bash theme={null}
curl -X POST "https://app.strix.ai/api/v1/scans/<SCAN_ID>/retest-all" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>"
```

**Required scope:** `scans:write`

## Get a reusable template

Get the configuration of a pentest as a template. You can use the template to start new pentests:

```bash theme={null}
curl -X GET "https://app.strix.ai/api/v1/scans/<SCAN_ID>/template" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>"
```

**Required scope:** `scans:read`

## Delete a pentest

```bash theme={null}
curl -X DELETE "https://app.strix.ai/api/v1/scans/<SCAN_ID>" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>"
```

**Required scope:** `scans:write`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.