Scans

Start and manage penetration test scans

POST/v1/scans

Create a scan

Initiate a new penetration test scan against a verified target. The scan is queued and will begin once a container is provisioned. A quota check is performed before the scan is enqueued. For retests, specify the parent scan 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 scan can be created. Returns 402 if insufficient credits and 409 if a scan is already running for this target.

Request Body

Name	Type	Description
`targetId`required	`string`	ID of the verified target to scan (must be verified)
`isRetest`	`boolean`	Whether this scan is a retest of previously found vulnerabilities
`parentScanId`	`string`	ID of the original scan 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 scan 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 scan object with its queue position and estimated start time. The scan 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 scan cost

Calculate the credit cost for a scan 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 scan 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 scans

Retrieve a paginated list of all scans for your account. Optionally filter by scan 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 scan 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 scans 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 scan details

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

Path Parameters

Name	Type	Description
`id`required	`string`	Scan 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 scan 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"
    },
    "scanner": {
      "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 scan

Cancel a scan that is currently in the queued or pending_verification status. Scans that are already provisioning or running cannot be cancelled through this endpoint. Cancelled scans refund the charged credits.

Only scans in `queued` or `pending_verification` status can be cancelled. Returns 409 if the scan has already started provisioning or running.

Path Parameters

Name	Type	Description
`id`required	`string`	Scan 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 scan 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 scan messages (SSE)

Open a Server-Sent Events stream to receive real-time agent messages for a running scan. Messages include agent thoughts, tool executions, findings discovered, status changes, and progress updates. The stream remains open until the scan 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`	Scan 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` (scan 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":"scanner","type":"tool_execution","tool":"nmap","content":"Running port scan 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":"scanner","timestamp":"2026-04-10T10:45:18Z"}

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

Back to API Reference