Pentests

Start and manage penetration test pentests

POST/v1/scans

Create a pentest

Initiate a new penetration test pentest against a verified target. The pentest is queued and will begin once a container is provisioned. A quota check is performed before the pentest is enqueued. For retests, specify the parent pentest ID and optionally limit the retest to specific finding IDs. The model preset controls which AI models are used and affects credit cost.

The target must be verified before a pentest can be created. Returns 402 if insufficient credits and 409 if a pentest is already running for this target.

Request Body

Name	Type	Description
`targetId`required	`string`	ID of the verified target to pentest (must be verified)
`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	AI model quality preset. Higher presets use more capable models and consume more credits
`promoCode`	`string`	Optional promotional code for discounted credits

Example Request

bash

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

Response

Returns the newly created pentest object with its queue position and estimated start time. The pentest will transition through statuses: queued -> provisioning -> running -> completed (or failed/cancelled).

json

{
  "id": "019414c3-d5e6-7f8a-b9c0-1d2e3f4a5b6c",
  "targetId": "019414a8-f7c0-7d4a-b5e3-9c2d1e8f4a6b",
  "target": {
    "domain": "example.com"
  },
  "status": "queued",
  "isRetest": false,
  "parentScanId": null,
  "modelPreset": "high",
  "creditsCharged": 15,
  "queuePosition": 1,
  "estimatedStartAt": "2026-04-10T10:32:00Z",
  "createdAt": "2026-04-10T10:30:14Z",
  "updatedAt": "2026-04-10T10:30:14Z"
}

POST/v1/scans/estimate

Estimate pentest cost

Calculate the credit cost for a pentest without actually creating it. Use this to display cost previews to users or to programmatically decide which model preset to use based on remaining credits.

Request Body

Name	Type	Description
`targetId`required	`string`	ID of the target to estimate
`isRetest`	`boolean`	Whether this would be a retest (retests cost less)
`modelPreset`	`string` freelowmediumhighultra	AI model quality preset
`promoCode`	`string`	Optional promotional code to factor into the estimate

Example Request

bash

curl -X POST "https://apviso.com/api/v1/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 the estimated credit cost, remaining balance preview, affordability check, and estimated pentest duration range.

json

{
  "credits": 15,
  "discount": null,
  "finalCredits": 15,
  "remaining": {
    "before": 373,
    "after": 358
  },
  "canAfford": true,
  "estimatedDuration": {
    "min": 25,
    "max": 45,
    "unit": "minutes"
  }
}

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

Name	Type	Description
`page`	`number` Default: `1`	Page number for pagination
`limit`	`number` Default: `20`	Number of results per page (max 100)
`status`	`string` queuedprovisioningrunningcompletedfailedcancelled	Filter by pentest status

Example Request

bash

curl -X GET "https://apviso.com/api/v1/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.

json

{
  "data": [
    {
      "id": "019414c3-d5e6-7f8a-b9c0-1d2e3f4a5b6c",
      "targetId": "019414a8-f7c0-7d4a-b5e3-9c2d1e8f4a6b",
      "target": {
        "domain": "example.com"
      },
      "status": "completed",
      "isRetest": false,
      "parentScanId": null,
      "modelPreset": "high",
      "creditsCharged": 15,
      "findingsCount": {
        "critical": 1,
        "high": 3,
        "medium": 5,
        "low": 8,
        "info": 4
      },
      "startedAt": "2026-04-10T10:32:08Z",
      "completedAt": "2026-04-10T11:04:52Z",
      "duration": 1964,
      "createdAt": "2026-04-10T10:30:14Z",
      "updatedAt": "2026-04-10T11:04:52Z"
    },
    {
      "id": "019414b8-e2f3-7a4b-c5d6-7e8f9a0b1c2d",
      "targetId": "019414b2-a3d1-7e8b-c4f6-1d2e3f4a5b6c",
      "target": {
        "domain": "staging.example.com"
      },
      "status": "running",
      "isRetest": false,
      "parentScanId": null,
      "modelPreset": "medium",
      "creditsCharged": 8,
      "findingsCount": {
        "critical": 0,
        "high": 1,
        "medium": 2,
        "low": 0,
        "info": 1
      },
      "startedAt": "2026-04-10T14:15:22Z",
      "completedAt": null,
      "duration": null,
      "createdAt": "2026-04-10T14:14:50Z",
      "updatedAt": "2026-04-10T14:15:22Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 2,
    "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

Name	Type	Description
`id`required	`string`	Pentest ID (UUIDv7)

Example Request

bash

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

Response

Returns the full pentest object including per-agent status and model information, findings breakdown, report availability, and timing details. Duration is in seconds.

json

{
  "id": "019414c3-d5e6-7f8a-b9c0-1d2e3f4a5b6c",
  "targetId": "019414a8-f7c0-7d4a-b5e3-9c2d1e8f4a6b",
  "target": {
    "domain": "example.com",
    "verified": true
  },
  "status": "completed",
  "isRetest": false,
  "parentScanId": null,
  "modelPreset": "high",
  "creditsCharged": 15,
  "agents": {
    "recon": {
      "status": "completed"
    },
    "pentester": {
      "status": "completed"
    },
    "lead": {
      "status": "completed"
    },
    "reporter": {
      "status": "completed"
    }
  },
  "findingsCount": {
    "critical": 1,
    "high": 3,
    "medium": 5,
    "low": 8,
    "info": 4
  },
  "reportReady": true,
  "queuePosition": null,
  "startedAt": "2026-04-10T10:32:08Z",
  "completedAt": "2026-04-10T11:04:52Z",
  "duration": 1964,
  "createdAt": "2026-04-10T10:30:14Z",
  "updatedAt": "2026-04-10T11:04:52Z"
}

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

Name	Type	Description
`id`required	`string`	Pentest ID (UUIDv7)

Example Request

bash

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

Response

Returns the updated pentest status and the number of credits refunded.

json

{
  "id": "019414c3-d5e6-7f8a-b9c0-1d2e3f4a5b6c",
  "status": "cancelled",
  "creditsRefunded": 15,
  "cancelledAt": "2026-04-10T10:31:02Z"
}

GET/v1/scans/:id/messages

Stream pentest messages (SSE)

Open a Server-Sent Events stream to receive real-time agent messages for a running pentest. Messages include agent thoughts, tool executions, findings discovered, status changes, and progress updates. The stream remains open until the pentest completes or is cancelled.

This endpoint returns `text/event-stream`, not JSON. Use an SSE client library (e.g., EventSource in browsers, or eventsource for Node.js). The stream replays recent messages on reconnection using the `Last-Event-ID` header.

Path Parameters

Name	Type	Description
`id`required	`string`	Pentest ID (UUIDv7)

Example Request

bash

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

Response

Returns a Server-Sent Events stream (text/event-stream). Event types include `agent_message` (agent thoughts and tool executions), `finding` (new vulnerability discovered), `status_change` (pentest status transitions), and `progress` (percentage completion updates). The connection is kept alive with periodic heartbeat comments.

json

event: agent_message
data: {"agent":"recon","type":"thought","content":"Starting subdomain enumeration for example.com...","timestamp":"2026-04-10T10:32:15Z"}

event: agent_message
data: {"agent":"pentester","type":"tool_execution","tool":"nmap","content":"Running port pentest on 93.184.216.34","timestamp":"2026-04-10T10:33:42Z"}

event: finding
data: {"id":"019414c8-a1b2-7c3d-e4f5-6a7b8c9d0e1f","severity":"high","title":"SQL Injection in /api/users","agent":"pentester","timestamp":"2026-04-10T10:45:18Z"}

event: status_change
data: {"status":"completed","timestamp":"2026-04-10T11:04:52Z"}

Back to API Reference