Pentests API - apviso [APVISO](/)Product

Resources

Developers

Company

[Pricing](/#pricing)[Partners](/partners)[Enterprise](/enterprise)

[Login](/login)[Start free pentest](/register?intent=free-local-pentest)

[Login](/login)[Start free](/register?intent=free-local-pentest)

[Home](/)[Knowledge Base](/docs)[API Reference](/docs/api)PentestsPentests
========

Start and manage penetration test pentests

POST`/v1/scans`

### Create a pentest

Create a self-hosted runner job for a target. APVISO records a `pending\_runner` scan and returns a runner job; an online runner claims the job, performs preflight, launches the pinned scan image, and streams results back with a job-scoped token. For retests, specify the parent pentest ID and optionally limit the retest to specific finding IDs.

Requires an active self-hosted license, allowed target visibility, at least one healthy runner, available runner concurrency, and a configured immutable `APVISO_SCAN_IMAGE_DIGEST` on the platform.

#### Request Body

NameTypeDescription`targetId`required

`string`ID of the target to pentest. Ownership verification is not required for self-hosted targets.`runnerId`

`string`Optional runner ID. When omitted, any eligible online runner for the organization can claim the job.`isRetest`

`boolean`Whether this pentest is a retest of previously found vulnerabilities`parentScanId`

`string`ID of the original pentest when running a retest. Required if isRetest is true`findingIds`

`string[]`Specific finding IDs to retest. If omitted during a retest, all findings from the parent pentest are retested`modelPreset`

`string`freelowmediumhighultra

Pentest depth preset. Model provider credentials and actual model routing are runner-local BYOK configuration.`promoCode`

`string`Deprecated compatibility field; ignored in self-hosted BYOK mode

#### Example Request

bashCopy

```
curl -X POST "https://apviso.com/api/v1/scans" \
  -H "X-API-Key: apvk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "targetId": "019414a8-f7c0-7d4a-b5e3-9c2d1e8f4a6b",
  "runnerId": "runner-1",
  "modelPreset": "high"
}'
```

#### Response

Returns the new scan and runner job. The normal self-hosted lifecycle is `pending\_runner` -> `assigned` -> `running` -> `completed` (or `preflight\_failed`, `failed`, or `cancelled`).

jsonCopy

```
{
  "scan": {
    "id": "019414c3-d5e6-7f8a-b9c0-1d2e3f4a5b6c",
    "targetId": "019414a8-f7c0-7d4a-b5e3-9c2d1e8f4a6b",
    "status": "pending_runner",
    "runnerId": "runner-1",
    "executionMode": "self_hosted_runner",
    "targetVisibility": "public",
    "scanImageDigest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "isRetest": false,
    "parentScanId": null,
    "config": {
      "modelPreset": "high",
      "execution": "self_hosted_runner"
    },
    "createdAt": "2026-05-03T09:30:14Z"
  },
  "runnerJob": {
    "id": "job-1",
    "scanId": "019414c3-d5e6-7f8a-b9c0-1d2e3f4a5b6c",
    "runnerId": "runner-1",
    "status": "pending_runner",
    "imageRef": "ghcr.io/apviso/scan",
    "imageDigest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "updateChannel": "stable"
  }
}
```

POST`/v1/scans/estimate`

### Estimate pentest readiness

Check self-hosted license, target visibility, and runner readiness without creating a scan.

#### Request Body

NameTypeDescription`targetId`required

`string`ID of the target to estimate`isRetest`

`boolean`Whether this would be a retest (retests cost less)`modelPreset`

`string`freelowmediumhighultra

Pentest depth preset`promoCode`

`string`Optional promotional code to factor into the estimate

#### Example Request

bashCopy

```
curl -X POST "https://apviso.com/api/v1/scans/estimate" \
  -H "X-API-Key: apvk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "targetId": "019414a8-f7c0-7d4a-b5e3-9c2d1e8f4a6b",
  "modelPreset": "high"
}'
```

#### Response

Returns readiness booleans and license/runner context. `priceCents` is zero in self-hosted BYOK mode.

jsonCopy

```
{
  "source": "self_hosted_license",
  "priceCents": 0,
  "hasPaymentMethod": true,
  "eligible": true,
  "runnerOk": true,
  "visibilityOk": true,
  "license": {
    "plan": "team",
    "licenseState": "active",
    "runnerLimit": 10,
    "concurrentJobLimit": 10
  },
  "runners": [
    {
      "id": "runner-1",
      "name": "prod-runner-1",
      "status": "online"
    }
  ]
}
```

GET`/v1/scans`

### List pentests

Retrieve a paginated list of all pentests for your account. Optionally filter by pentest status. Results are ordered by creation date (newest first).

#### Query Parameters

NameTypeDescription`page`

`number`Default: `1`

Page number for pagination`limit`

`number`Default: `20`

Number of results per page (max 100)`status`

`string`pending\_runnerassignedqueuedprovisioningpreflight\_failedrunningstalecompletedfailedcancelled

Filter by pentest status

#### Example Request

bashCopy

```
curl -X GET "https://apviso.com/api/v1/scans" \
  -H "X-API-Key: apvk_your_key_here"
```

#### Response

Returns a paginated list of pentests with findings count breakdown by severity, timing information, and duration in seconds.

jsonCopy

```
{
  "scans": [
    {
      "id": "019414c3-d5e6-7f8a-b9c0-1d2e3f4a5b6c",
      "targetId": "019414a8-f7c0-7d4a-b5e3-9c2d1e8f4a6b",
      "target": {
        "domain": "example.com"
      },
      "status": "completed",
      "executionMode": "self_hosted_runner",
      "runnerId": "runner-1",
      "isRetest": false,
      "parentScanId": null,
      "config": {
        "modelPreset": "high",
        "execution": "self_hosted_runner"
      },
      "startedAt": "2026-05-03T09:32:08Z",
      "completedAt": "2026-05-03T10:04:52Z",
      "createdAt": "2026-05-03T09:30:14Z"
    },
    {
      "id": "019414b8-e2f3-7a4b-c5d6-7e8f9a0b1c2d",
      "targetId": "019414b2-a3d1-7e8b-c4f6-1d2e3f4a5b6c",
      "target": {
        "domain": "staging.example.com"
      },
      "status": "pending_runner",
      "executionMode": "self_hosted_runner",
      "runnerId": null,
      "isRetest": false,
      "parentScanId": null,
      "config": {
        "modelPreset": "medium",
        "execution": "self_hosted_runner"
      },
      "startedAt": null,
      "completedAt": null,
      "createdAt": "2026-05-03T10:14:50Z"
    }
  ],
  "total": 2,
  "page": 1,
  "limit": 20,
  "totalPages": 1
}
```

GET`/v1/scans/:id`

### Get pentest details

Retrieve detailed information about a specific pentest, including its current status, agent progress, findings summary, and timing data.

#### Path Parameters

NameTypeDescription`id`required

`string`Pentest ID (UUIDv7)

#### Example Request

bashCopy

```
curl -X GET "https://apviso.com/api/v1/scans/:id" \
  -H "X-API-Key: apvk_your_key_here"
```

#### Response

Returns the full pentest object with self-hosted runner metadata, target details, status, and timing fields.

jsonCopy

```
{
  "scan": {
    "id": "019414c3-d5e6-7f8a-b9c0-1d2e3f4a5b6c",
    "targetId": "019414a8-f7c0-7d4a-b5e3-9c2d1e8f4a6b",
    "target": {
      "domain": "example.com",
      "authConfigMode": "runner_local"
    },
    "status": "completed",
    "executionMode": "self_hosted_runner",
    "runnerId": "runner-1",
    "isRetest": false,
    "parentScanId": null,
    "config": {
      "modelPreset": "high",
      "execution": "self_hosted_runner"
    },
    "scanImageDigest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "startedAt": "2026-05-03T09:32:08Z",
    "completedAt": "2026-05-03T10:04:52Z",
    "createdAt": "2026-05-03T09:30:14Z"
  }
}
```

POST`/v1/scans/:id/cancel`

### Cancel a pentest

Cancel a pentest that is currently queued or active. Self-hosted runner jobs receive a cancellation request and stop as soon as possible.

Self-hosted pentests can be cancelled while pending runner assignment, assigned, preflight failed, queued, provisioning, running, stale, or legacy pending verification.

#### Path Parameters

NameTypeDescription`id`required

`string`Pentest ID (UUIDv7)

#### Example Request

bashCopy

```
curl -X POST "https://apviso.com/api/v1/scans/:id/cancel" \
  -H "X-API-Key: apvk_your_key_here"
```

#### Response

Returns the updated pentest status. Self-hosted BYOK mode does not issue APVISO-hosted scan refunds.

jsonCopy

```
{
  "scan": {
    "id": "019414c3-d5e6-7f8a-b9c0-1d2e3f4a5b6c",
    "status": "cancelled",
    "completedAt": "2026-05-03T09:31:02Z"
  },
  "refunded": false
}
```

[Back to API Reference](/docs/api)

[Overview](#overview)[POST /v1/scans](#create-scan)[POST /v1/scans/estimate](#estimate-scan-readiness)[GET /v1/scans](#list-scans)[GET /v1/scans/:id](#get-scan)[POST /v1/scans/:id/cancel](#cancel-scan)

[APVISO](/)Autonomous AI-powered penetration testing for modern web applications.

Subscribe

[](https://github.com/apviso)[](https://x.com/Apviso_com)[](https://www.linkedin.com/company/apviso/)

[![Featured on Good AI Tools](https://goodaitools.com/assets/images/badge.png)](https://goodaitools.com/ai/apviso)

Product

- [Features](/#features)
- [Pricing](/pricing)
- [Integrations](/integrations)
- [Benchmarks](/#compare)
- [Affiliate Program](/affiliate)
- [Partners](/partners)
- [Enterprise](/enterprise)

Resources

- [Blog](/blog)
- [Use Cases](/use-cases)
- [Glossary](/glossary)
- [Comparisons](/comparisons)
- [Alternatives](/alternatives)
- [Compliance](/compliance)
- [Vulnerabilities](/vulnerabilities)
- [Industries](/industries)
- [OWASP APTS](/trust/apts)

Developers

- [Knowledge Base](/docs)
- [API Reference](/docs/api)
- [MCP Server](/docs/mcp)

Company

- [About](/about)
- [Contact](/contact)
- [Status](https://status.apviso.com)
- [Privacy Policy](/legal/privacy)
- [Terms of Service](/legal/terms)

© 2026 APVISO. All rights reserved.