MCP Server Documentation - 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)MCP ServerMCP Server Documentation
========================

The `@apviso/mcp` package connects your AI assistant to the APVISO self-hosted BYOK penetration testing platform via the Model Context Protocol. Manage runners, targets, pentests, findings, and reports without leaving your editor.

**25 tools** across 7 categories - license, runners, targets, pentests, findings, reports, and schedules.

Installation
------------

No installation needed - the package runs via `npx`. Just configure your AI tool with the correct settings below.

Configuration
-------------

Choose your AI tool and add the configuration below. You'll need an APVISO API key; runner tokens and BYOK provider credentials stay on the self-hosted runner. Generate the API key in **Settings → API Keys**.

### Claude Code

Add the MCP server to Claude Code via the CLI. The server runs as a stdio transport.

bashCopy

```
claude mcp add --transport stdio apviso \
  --env APVISO_API_KEY=apvk_your_key_here \
  -- npx -y @apviso/mcp
```

### Claude Desktop

Add the following to your Claude Desktop configuration file (claude\_desktop\_config.json).

jsonCopy

```
{
  "mcpServers": {
    "apviso": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@apviso/mcp"
      ],
      "env": {
        "APVISO_API_KEY": "apvk_your_key_here"
      }
    }
  }
}
```

### Cursor

Add the following to your Cursor MCP configuration file (.cursor/mcp.json in your project root or ~/.cursor/mcp.json globally).

jsonCopy

```
{
  "mcpServers": {
    "apviso": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@apviso/mcp"
      ],
      "env": {
        "APVISO_API_KEY": "apvk_your_key_here"
      }
    }
  }
}
```

### Windsurf

Add the following to your Windsurf MCP configuration file (~/.codeium/windsurf/mcp\_config.json).

jsonCopy

```
{
  "mcpServers": {
    "apviso": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@apviso/mcp"
      ],
      "env": {
        "APVISO_API_KEY": "apvk_your_key_here"
      }
    }
  }
}
```

### VS Code

Add the following to your VS Code settings.json (User or Workspace).

jsonCopy

```
{
  "mcp": {
    "servers": {
      "apviso": {
        "type": "stdio",
        "command": "npx",
        "args": [
          "-y",
          "@apviso/mcp"
        ],
        "env": {
          "APVISO_API_KEY": "apvk_your_key_here"
        }
      }
    }
  }
}
```

Environment Variables
---------------------

VariableRequiredDescriptionDefault`APVISO_API_KEY`YesAPI key starting with "apvk\_". Generate one in Settings → API Keys.None`APVISO_API_URL`NoOverride the API origin or base URL. Values ending in /api or /api/v1 are normalized automatically.`https://api.apviso.com`

Tool Reference
--------------

All 25 tools available in the APVISO MCP server.

### License & Readiness

Check self-hosted license and runner readiness.

`get_quota`

Returns your current subscription tier and self-hosted license details. New pentests are authorized by license state, runner health, target visibility, and runner concurrency.

No parameters required.

#### Returns

Subscription tier name and self-hosted license details. Use runner readiness to check whether a specific scan can start.

#### Example Input

jsonCopy

```
{}
```

#### Example Output

jsonCopy

```
{
  "tier": "team",
  "source": "self_hosted_license",
  "license": {
    "plan": "team",
    "licenseState": "active",
    "canStartSelfHostedScan": true,
    "runnerLimit": 10,
    "concurrentJobLimit": 10
  }
}
```

### Runners

Register and monitor self-hosted BYOK scan runners.

`list_runners`

Returns registered self-hosted runners plus organization-level readiness. Runners execute BYOK pentests from your infrastructure; APVISO coordinates jobs and receives results.

No parameters required.

#### Returns

Runner records with redacted token metadata, provider capability state, heartbeat status, and a readiness summary.

#### Example Input

jsonCopy

```
{}
```

#### Example Output

jsonCopy

```
{
  "runners": [
    {
      "id": "runner-1",
      "name": "prod-runner-1",
      "status": "online",
      "version": "0.1.5",
      "configuredConcurrency": 1,
      "currentJobs": 0,
      "providerState": {
        "modelProvider": "openai-codex",
        "embeddingProvider": "local"
      },
      "lastHeartbeatAt": "2026-05-03T09:15:32Z"
    }
  ],
  "readiness": {
    "ready": true,
    "runnerOk": true,
    "visibilityOk": true,
    "runners": [
      {
        "id": "runner-1",
        "name": "prod-runner-1",
        "status": "online"
      }
    ]
  }
}
```

`get_runner_readiness`

Checks whether the current license, optional target visibility, optional selected runner, and runner heartbeats allow a self-hosted pentest to start.

#### Parameters

NameTypeDescription`targetId`

`string`Optional target ID to include target visibility checks.`runnerId`

`string`Optional runner ID to require a specific online runner.

#### Returns

Readiness booleans, license details, selected runner context, and eligible runners.

#### Example Input

jsonCopy

```
{
  "targetId": "019560a5-1b40-7d2c-ae3f-b6c7d8e9f0a1"
}
```

#### Example Output

jsonCopy

```
{
  "ready": true,
  "visibility": "private_internal",
  "visibilityOk": true,
  "runnerOk": true,
  "selectedRunnerId": null,
  "license": {
    "plan": "team",
    "licenseState": "active",
    "runnerLimit": 10,
    "concurrentJobLimit": 10
  },
  "runners": [
    {
      "id": "runner-1",
      "name": "prod-runner-1",
      "status": "online"
    }
  ]
}
```

`create_runner_enrollment_token`

Creates a short-lived, one-time enrollment token used by `apviso register --token ...` or runner onboarding.

Runner daemons should run with `APVISO_RUNNER_TOKEN`, not a user API key. BYOK provider credentials stay on the runner host.

#### Parameters

NameTypeDescription`name`

`string`Suggested runner name shown during registration.

#### Returns

Raw enrollment token, token prefix, and expiration timestamp. The raw token is returned once.

#### Example Input

jsonCopy

```
{
  "name": "prod-runner-1"
}
```

#### Example Output

jsonCopy

```
{
  "token": "apve_a1b2c3d4e5f6_redacted",
  "tokenPrefix": "a1b2c3d4e5f6",
  "expiresAt": "2026-05-03T09:45:32Z"
}
```

### Targets

Register and manage self-hosted pentest targets.

`list_targets`

Returns a paginated list of targets registered to your account, including display URL, runner scan URL, visibility, and runner-local auth mode.

#### Parameters

NameTypeDescription`page`

`number`Page number for pagination.`limit`

`number`Default: `20`

Number of targets per page.

#### Returns

Paginated array of targets with id, domain, display URL, scan URL, visibility, and timestamps.

#### Example Input

jsonCopy

```
{
  "page": 1,
  "limit": 10
}
```

#### Example Output

jsonCopy

```
{
  "targets": [
    {
      "id": "019560a4-7c30-7f3a-8b2e-d4f5a6b7c8d9",
      "domain": "example.com",
      "displayUrl": "https://example.com",
      "scanUrl": "https://example.com",
      "visibility": "public",
      "authConfigMode": "runner_local",
      "createdAt": "2026-03-15T10:30:00Z"
    },
    {
      "id": "019560a4-9e10-7a1b-bc4d-e5f6a7b8c9d0",
      "domain": "staging.example.com",
      "displayUrl": "https://staging.example.com",
      "scanUrl": "http://host.docker.internal:4000",
      "visibility": "localhost",
      "authConfigMode": "runner_local",
      "createdAt": "2026-04-09T08:15:00Z"
    }
  ],
  "page": 1,
  "limit": 10,
  "total": 2,
  "totalPages": 1
}
```

`get_target`

Returns full details for a single target, including display URL, runner scan URL, visibility, execution mode, and runner-local auth mode.

#### Parameters

NameTypeDescription`targetId`required

`string`UUIDv7 identifier of the target.

#### Returns

Target object with id, domain, display URL, scan URL, visibility, and timestamps.

#### Example Input

jsonCopy

```
{
  "targetId": "019560a4-7c30-7f3a-8b2e-d4f5a6b7c8d9"
}
```

#### Example Output

jsonCopy

```
{
  "target": {
    "id": "019560a4-7c30-7f3a-8b2e-d4f5a6b7c8d9",
    "domain": "example.com",
    "displayUrl": "https://example.com",
    "scanUrl": "https://example.com",
    "visibility": "public",
    "executionMode": "self_hosted_runner",
    "authConfigMode": "runner_local",
    "createdAt": "2026-03-15T10:30:00Z"
  }
}
```

`create_target`

Registers a new self-hosted target. Ownership verification is no longer required; scan starts are gated by license, target visibility, and runner readiness.

Pentest starts are gated by license state, target visibility, and runner readiness. Deprecated verification tools remain for compatibility only.

#### Parameters

NameTypeDescription`domain`required

`string`Canonical domain, host, IP, or URL label for the target.`displayUrl`

`string`Human-facing URL shown in APVISO. Defaults to domain.`scanUrl`

`string`Runtime URL the runner should scan. Use for private, localhost, or split-horizon targets.`visibility`

`string`publicstaging\_previewprivate\_internallocalhostpartner\_client

Target visibility class used for license and runner networking checks.`partnerClientId`

`string`Partner client ID. Required when visibility is partner\_client.

#### Returns

Newly created target object with id, domain, visibility, execution mode, and runner-local auth mode.

#### Example Input

jsonCopy

```
{
  "domain": "staging.example.com",
  "displayUrl": "https://staging.example.com",
  "scanUrl": "http://host.docker.internal:4000",
  "visibility": "localhost"
}
```

#### Example Output

jsonCopy

```
{
  "target": {
    "id": "019560a5-1b40-7d2c-ae3f-b6c7d8e9f0a1",
    "domain": "staging.example.com",
    "displayUrl": "https://staging.example.com",
    "scanUrl": "http://host.docker.internal:4000",
    "visibility": "localhost",
    "executionMode": "self_hosted_runner",
    "authConfigMode": "runner_local",
    "createdAt": "2026-05-03T09:00:00Z"
  }
}
```

`verify_target`

Deprecated compatibility tool. Self-hosted targets do not require DNS, file, or meta-tag ownership verification.

#### Parameters

NameTypeDescription`targetId`required

`string`UUIDv7 identifier of the target to verify.`method`

`string`dns\_txtfilemeta\_tag

Ignored compatibility field.

#### Returns

Compatibility response with verified=true and deprecated=true.

#### Example Input

jsonCopy

```
{
  "targetId": "019560a5-1b40-7d2c-ae3f-b6c7d8e9f0a1",
  "method": "dns_txt"
}
```

#### Example Output

jsonCopy

```
{
  "id": "019560a5-1b40-7d2c-ae3f-b6c7d8e9f0a1",
  "domain": "app.example.com",
  "verified": true,
  "deprecated": true
}
```

`get_verification_instructions`

Deprecated compatibility tool. Self-hosted targets do not have verification tokens.

#### Parameters

NameTypeDescription`targetId`required

`string`UUIDv7 identifier of the target.

#### Returns

Empty compatibility payload with deprecated=true.

#### Example Input

jsonCopy

```
{
  "targetId": "019560a5-1b40-7d2c-ae3f-b6c7d8e9f0a1"
}
```

#### Example Output

jsonCopy

```
{
  "token": null,
  "methods": {},
  "deprecated": true,
  "message": "Target ownership verification is no longer required for self-hosted runners."
}
```

`delete_target`

Permanently deletes a target. This will fail if the target has any associated pentests. Remove all pentests first if you need to delete the target.

Cannot delete a target that has associated pentests. This is irreversible.

#### Parameters

NameTypeDescription`targetId`required

`string`UUIDv7 identifier of the target to delete.

#### Returns

Confirmation message on success.

#### Example Input

jsonCopy

```
{
  "targetId": "019560a4-9e10-7a1b-bc4d-e5f6a7b8c9d0"
}
```

#### Example Output

jsonCopy

```
{
  "message": "Target deleted successfully."
}
```

### Pentests

Start and monitor pentests.

`list_scans`

Returns a paginated list of pentests, optionally filtered by status. Includes pentest id, target domain, status, timestamps, and finding counts.

#### Parameters

NameTypeDescription`page`

`number`Page number for pagination.`limit`

`number`Default: `20`

Number of pentests per page.`status`

`string`pending\_verificationpending\_runnerqueuedassignedprovisioningpreflight\_failedrunningstalecompletedfailedcancelled

Filter pentests by status.

#### Returns

Paginated array of pentests with id, target info, status, timing, and finding summary.

#### Example Input

jsonCopy

```
{
  "status": "completed",
  "limit": 5
}
```

#### Example Output

jsonCopy

```
{
  "data": [
    {
      "id": "019560b2-3a50-7e4d-bf60-c8d9eaf1b2c3",
      "targetId": "019560a4-7c30-7f3a-8b2e-d4f5a6b7c8d9",
      "targetDomain": "example.com",
      "status": "completed",
      "isRetest": false,
      "modelPreset": "high",
      "findingsSummary": {
        "critical": 1,
        "high": 3,
        "medium": 7,
        "low": 4,
        "info": 12
      },
      "startedAt": "2026-04-08T14:22:00Z",
      "completedAt": "2026-04-08T15:48:00Z",
      "createdAt": "2026-04-08T14:20:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 5,
    "total": 1,
    "totalPages": 1
  }
}
```

`get_scan`

Returns detailed information about a specific pentest, including its current status, configuration, timing, and high-level finding counts.

#### Parameters

NameTypeDescription`scanId`required

`string`UUIDv7 identifier of the pentest.

#### Returns

Full pentest object with id, target, status, model preset, timing, and findings summary.

#### Example Input

jsonCopy

```
{
  "scanId": "019560b2-3a50-7e4d-bf60-c8d9eaf1b2c3"
}
```

#### Example Output

jsonCopy

```
{
  "id": "019560b2-3a50-7e4d-bf60-c8d9eaf1b2c3",
  "targetId": "019560a4-7c30-7f3a-8b2e-d4f5a6b7c8d9",
  "targetDomain": "example.com",
  "status": "completed",
  "isRetest": false,
  "parentScanId": null,
  "modelPreset": "high",
  "findingsSummary": {
    "critical": 1,
    "high": 3,
    "medium": 7,
    "low": 4,
    "info": 12
  },
  "startedAt": "2026-04-08T14:22:00Z",
  "completedAt": "2026-04-08T15:48:00Z",
  "createdAt": "2026-04-08T14:20:00Z"
}
```

`create_scan`

Creates a self-hosted runner job for a target. APVISO records a pending\_runner scan; an online runner claims the job, performs preflight, launches the pinned scan image, and streams results back with a job-scoped token.

Requires an active self-hosted license, an eligible target visibility, a healthy runner, available runner concurrency, and a configured scan image digest.

#### Parameters

NameTypeDescription`targetId`required

`string`UUIDv7 identifier of the target to pentest.`runnerId`

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

`boolean`Default: `false`

Set to true to run a retest instead of a full pentest. Retests focus on previously found vulnerabilities.`parentScanId`

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

`string[]`Array of finding UUIDv7 IDs to retest. When omitted during a retest, all findings from the parent pentest are retested.`modelPreset`

`string`freelowmediumhighultra

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

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

#### Returns

Newly created pentest object and runner job. Normal status starts at pending\_runner.

#### Example Input

jsonCopy

```
{
  "targetId": "019560a4-7c30-7f3a-8b2e-d4f5a6b7c8d9",
  "runnerId": "runner-1",
  "modelPreset": "high"
}
```

#### Example Output

jsonCopy

```
{
  "scan": {
    "id": "019560c8-5d70-7f8a-c1b2-d3e4f5a6b7c8",
    "targetId": "019560a4-7c30-7f3a-8b2e-d4f5a6b7c8d9",
    "targetDomain": "example.com",
    "status": "pending_runner",
    "runnerId": "runner-1",
    "isRetest": false,
    "config": {
      "modelPreset": "high",
      "execution": "self_hosted_runner"
    },
    "createdAt": "2026-05-03T09:10:00Z"
  },
  "runnerJob": {
    "id": "job-1",
    "status": "pending_runner"
  }
}
```

`estimate_scan_readiness`

Checks self-hosted license, target visibility, optional runner selection, and runner readiness without creating a scan.

#### Parameters

NameTypeDescription`targetId`required

`string`UUIDv7 identifier of the target to estimate.`runnerId`

`string`Optional runner ID to require a specific online runner.`isRetest`

`boolean`Whether this would be a retest.`parentScanId`

`string`Parent scan ID for retest estimates.`modelPreset`

`string`freelowmediumhighultra

Pentest depth preset.`promoCode`

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

#### Returns

Readiness booleans and license/runner context.

#### Example Input

jsonCopy

```
{
  "targetId": "019560a4-7c30-7f3a-8b2e-d4f5a6b7c8d9",
  "modelPreset": "high"
}
```

#### Example Output

jsonCopy

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

`cancel_scan`

Cancels a pending or active self-hosted scan. Runner jobs receive a cancellation request and stop as soon as possible.

#### Parameters

NameTypeDescription`scanId`required

`string`UUIDv7 identifier of the scan to cancel.

#### Returns

Updated scan status.

#### Example Input

jsonCopy

```
{
  "scanId": "019560c8-5d70-7f8a-c1b2-d3e4f5a6b7c8"
}
```

#### Example Output

jsonCopy

```
{
  "scan": {
    "id": "019560c8-5d70-7f8a-c1b2-d3e4f5a6b7c8",
    "status": "cancelled"
  },
  "refunded": false
}
```

### Findings

View and manage vulnerability findings.

`list_findings`

Returns a paginated list of vulnerability findings for a given pentest. Descriptions are truncated to 500 characters; use get\_report for the full details.

Descriptions are truncated to 500 characters. Use get_report for complete vulnerability details, reproduction steps, and remediation guidance.

#### Parameters

NameTypeDescription`scanId`required

`string`UUIDv7 identifier of the pentest.`page`

`number`Page number for pagination.`limit`

`number`Default: `20`

Number of findings per page.`severity`

`string`criticalhighmediumlowinfo

Filter by severity level.`userStatus`

`string`openin\_progressfixedaccepted\_riskfalse\_positive

Filter by remediation status.

#### Returns

Paginated array of findings with id, title, severity, CVSS score, user status, and truncated description.

#### Example Input

jsonCopy

```
{
  "scanId": "019560b2-3a50-7e4d-bf60-c8d9eaf1b2c3",
  "severity": "critical"
}
```

#### Example Output

jsonCopy

```
{
  "data": [
    {
      "id": "019560d1-8e90-7b3c-d4e5-f6a7b8c9d0e1",
      "scanId": "019560b2-3a50-7e4d-bf60-c8d9eaf1b2c3",
      "title": "SQL Injection in /api/users endpoint",
      "severity": "critical",
      "cvssScore": 9.8,
      "cvssVector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H",
      "userStatus": "open",
      "description": "A SQL injection vulnerability was identified in the /api/users endpoint. The 'id' parameter is directly concatenated into a SQL query without proper sanitization or parameterized queries. An unauthenticated attacker can extract, modify, or delete arbitrary data from the database, including user credentials and session tokens...",
      "cweId": "CWE-89",
      "affectedUrl": "https://example.com/api/users?id=1",
      "createdAt": "2026-04-08T14:45:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1
  }
}
```

`update_finding_status`

Updates the remediation status of a finding to track your progress. Use this to mark findings as in progress, fixed, accepted risk, or false positive.

#### Parameters

NameTypeDescription`findingId`required

`string`UUIDv7 identifier of the finding.`userStatus`required

`string`openin\_progressfixedaccepted\_riskfalse\_positive

New remediation status for the finding.

#### Returns

Updated finding object with the new user status.

#### Example Input

jsonCopy

```
{
  "findingId": "019560d1-8e90-7b3c-d4e5-f6a7b8c9d0e1",
  "userStatus": "in_progress"
}
```

#### Example Output

jsonCopy

```
{
  "id": "019560d1-8e90-7b3c-d4e5-f6a7b8c9d0e1",
  "title": "SQL Injection in /api/users endpoint",
  "severity": "critical",
  "userStatus": "in_progress",
  "updatedAt": "2026-04-10T09:30:00Z"
}
```

`reorder_findings`

Updates finding display order for report and dashboard views. Positions are zero-indexed.

#### Parameters

NameTypeDescription`scanId`required

`string`UUIDv7 identifier of the pentest.`positions`required

`array`Array of objects with findingId and zero-indexed position.

#### Returns

success=true after applying the new finding positions.

#### Example Input

jsonCopy

```
{
  "scanId": "019560b2-3a50-7e4d-bf60-c8d9eaf1b2c3",
  "positions": [
    {
      "findingId": "019560d1-8e90-7b3c-d4e5-f6a7b8c9d0e1",
      "position": 0
    },
    {
      "findingId": "019560d2-8e90-7b3c-d4e5-f6a7b8c9d0e2",
      "position": 1
    }
  ]
}
```

#### Example Output

jsonCopy

```
{
  "success": true
}
```

### Reports

Access full penetration test reports.

`get_report`

Returns the full penetration test report for a completed pentest in Markdown format, along with a signed URL to download the PDF version. Reports include an executive summary, detailed findings with reproduction steps, remediation guidance, and risk ratings. May return HTTP 202 if the report is still being generated.

If the report is still generating, the tool returns a short message telling you to retry. Use generate_report_pdf when you need the PDF URL populated.

#### Parameters

NameTypeDescription`scanId`required

`string`UUIDv7 identifier of the pentest to retrieve the report for.

#### Returns

Full Markdown report content, PDF download URL, and generation metadata.

#### Example Input

jsonCopy

```
{
  "scanId": "019560b2-3a50-7e4d-bf60-c8d9eaf1b2c3"
}
```

#### Example Output

jsonCopy

```
{
  "scanId": "019560b2-3a50-7e4d-bf60-c8d9eaf1b2c3",
  "status": "ready",
  "format": "markdown",
  "content": "# Penetration Test Report\\n\\n## Executive Summary\\n\\nA penetration test was conducted against example.com on April 8, 2026. The assessment identified 27 findings: 1 critical, 3 high, 7 medium, 4 low, and 12 informational...\\n\\n## Critical Findings\\n\\n### 1. SQL Injection in /api/users endpoint\\n\\n**Severity:** Critical (CVSS 9.8)\\n**CWE:** CWE-89\\n\\n#### Description\\n\\nA SQL injection vulnerability was identified...",
  "pdfUrl": "https://storage.apviso.com/reports/019560b2-3a50-7e4d-bf60-c8d9eaf1b2c3.pdf?sig=abc123&exp=1712750400",
  "pdfExpiresAt": "2026-04-10T12:00:00Z",
  "generatedAt": "2026-04-08T16:02:00Z"
}
```

`generate_report_pdf`

Generates the PDF report for a completed pentest. Repeated calls return ready=true if the PDF already exists.

Call get_report after generation to retrieve the report row and PDF URL when available.

#### Parameters

NameTypeDescription`scanId`required

`string`UUIDv7 identifier of the pentest to generate a PDF report for.

#### Returns

ready=true when the PDF has been generated or already exists.

#### Example Input

jsonCopy

```
{
  "scanId": "019560b2-3a50-7e4d-bf60-c8d9eaf1b2c3"
}
```

#### Example Output

jsonCopy

```
{
  "ready": true
}
```

### Schedules

Manage recurring pentest schedules. Requires Team tier or higher.

`list_schedules`

Returns all pentest schedules configured on your account, including their frequency, next run time, and enabled status.

No parameters required.

#### Returns

Array of schedule objects with id, target, frequency, timing, enabled status, and next run time.

#### Example Input

jsonCopy

```
{}
```

#### Example Output

jsonCopy

```
{
  "data": [
    {
      "id": "019560e4-a1b0-7c5d-e6f7-a8b9c0d1e2f3",
      "targetId": "019560a4-7c30-7f3a-8b2e-d4f5a6b7c8d9",
      "targetDomain": "example.com",
      "frequency": "weekly",
      "hour": 2,
      "minute": 0,
      "dayOfWeek": 1,
      "dayOfMonth": null,
      "modelPreset": "high",
      "enabled": true,
      "nextRunAt": "2026-04-14T02:00:00Z",
      "lastRunAt": "2026-04-07T02:00:00Z",
      "createdAt": "2026-03-20T15:00:00Z"
    }
  ]
}
```

`get_schedule`

Returns full details for a specific pentest schedule, including its configuration and execution history summary.

#### Parameters

NameTypeDescription`scheduleId`required

`string`UUIDv7 identifier of the schedule.

#### Returns

Schedule object with full configuration, timing, and recent execution history.

#### Example Input

jsonCopy

```
{
  "scheduleId": "019560e4-a1b0-7c5d-e6f7-a8b9c0d1e2f3"
}
```

#### Example Output

jsonCopy

```
{
  "id": "019560e4-a1b0-7c5d-e6f7-a8b9c0d1e2f3",
  "targetId": "019560a4-7c30-7f3a-8b2e-d4f5a6b7c8d9",
  "targetDomain": "example.com",
  "frequency": "weekly",
  "hour": 2,
  "minute": 0,
  "dayOfWeek": 1,
  "dayOfMonth": null,
  "modelPreset": "high",
  "enabled": true,
  "nextRunAt": "2026-04-14T02:00:00Z",
  "lastRunAt": "2026-04-07T02:00:00Z",
  "totalRuns": 3,
  "createdAt": "2026-03-20T15:00:00Z",
  "updatedAt": "2026-04-07T02:01:00Z"
}
```

`create_schedule`

Creates a new recurring pentest schedule for a self-hosted target. Requires Team tier or higher. Pentests run automatically at the specified time and frequency when runner capacity is available.

Requires Team tier or higher. Scheduled pentests use the organization's self-hosted runner license.

#### Parameters

NameTypeDescription`targetId`required

`string`UUIDv7 identifier of a self-hosted target.`frequency`required

`string`dailyweeklybiweeklymonthly

How often the pentest should run.`hour`required

`number`Hour of day to run the pentest (UTC).`minute`

`number`Default: `0`

Minute of the hour to run the pentest (UTC).`dayOfWeek`

`number`Day of week for weekly/biweekly schedules. 0 = Sunday, 6 = Saturday.`dayOfMonth`

`number`Day of month for monthly schedules. Limited to 1-28 to avoid month-length issues.`modelPreset`

`string`lowmediumhighultra

AI model quality preset for scheduled pentests.

#### Returns

Newly created schedule object with id, configuration, and next run time.

#### Example Input

jsonCopy

```
{
  "targetId": "019560a4-7c30-7f3a-8b2e-d4f5a6b7c8d9",
  "frequency": "weekly",
  "hour": 2,
  "minute": 0,
  "dayOfWeek": 1,
  "modelPreset": "high"
}
```

#### Example Output

jsonCopy

```
{
  "id": "019560f5-b2c0-7d6e-f8a9-b0c1d2e3f4a5",
  "targetId": "019560a4-7c30-7f3a-8b2e-d4f5a6b7c8d9",
  "targetDomain": "example.com",
  "frequency": "weekly",
  "hour": 2,
  "minute": 0,
  "dayOfWeek": 1,
  "dayOfMonth": null,
  "modelPreset": "high",
  "enabled": true,
  "nextRunAt": "2026-04-14T02:00:00Z",
  "createdAt": "2026-04-10T09:45:00Z"
}
```

`update_schedule`

Updates an existing pentest schedule. You can modify the frequency, timing, model preset, or enable/disable the schedule. Only provided fields are updated.

#### Parameters

NameTypeDescription`scheduleId`required

`string`UUIDv7 identifier of the schedule to update.`frequency`

`string`dailyweeklybiweeklymonthly

New frequency for the schedule.`hour`

`number`New hour of day (UTC).`minute`

`number`New minute of the hour (UTC).`dayOfWeek`

`number`New day of week (0 = Sunday, 6 = Saturday).`dayOfMonth`

`number`New day of month (1-28).`enabled`

`boolean`Set to false to pause the schedule without deleting it.`modelPreset`

`string`lowmediumhighultra

New model quality preset.

#### Returns

Updated schedule object reflecting the changes.

#### Example Input

jsonCopy

```
{
  "scheduleId": "019560e4-a1b0-7c5d-e6f7-a8b9c0d1e2f3",
  "enabled": false
}
```

#### Example Output

jsonCopy

```
{
  "id": "019560e4-a1b0-7c5d-e6f7-a8b9c0d1e2f3",
  "targetId": "019560a4-7c30-7f3a-8b2e-d4f5a6b7c8d9",
  "targetDomain": "example.com",
  "frequency": "weekly",
  "hour": 2,
  "minute": 0,
  "dayOfWeek": 1,
  "dayOfMonth": null,
  "modelPreset": "high",
  "enabled": false,
  "nextRunAt": null,
  "updatedAt": "2026-04-10T10:00:00Z"
}
```

`delete_schedule`

Permanently deletes a pentest schedule. Any currently queued or running pentest from this schedule will still complete, but no future pentests will be created.

This is irreversible. In-flight pentests spawned by this schedule will not be cancelled.

#### Parameters

NameTypeDescription`scheduleId`required

`string`UUIDv7 identifier of the schedule to delete.

#### Returns

Confirmation message on success.

#### Example Input

jsonCopy

```
{
  "scheduleId": "019560e4-a1b0-7c5d-e6f7-a8b9c0d1e2f3"
}
```

#### Example Output

jsonCopy

```
{
  "message": "Schedule deleted successfully."
}
```

[Back to Knowledge Base](/docs)

[Overview](#overview)

[Installation](#installation)

[Configuration](#configuration)

[Environment Variables](#environment)

[License & Readiness](#category-quota)[get\_quota](#tool-get_quota)

[Runners](#category-runners)[list\_runners](#tool-list_runners)[get\_runner\_readiness](#tool-get_runner_readiness)[create\_runner\_enrollment\_token](#tool-create_runner_enrollment_token)

[Targets](#category-targets)[list\_targets](#tool-list_targets)[get\_target](#tool-get_target)[create\_target](#tool-create_target)[verify\_target](#tool-verify_target)[get\_verification\_instructions](#tool-get_verification_instructions)[delete\_target](#tool-delete_target)

[Pentests](#category-pentests)[list\_scans](#tool-list_scans)[get\_scan](#tool-get_scan)[create\_scan](#tool-create_scan)[estimate\_scan\_readiness](#tool-estimate_scan_readiness)[cancel\_scan](#tool-cancel_scan)

[Findings](#category-findings)[list\_findings](#tool-list_findings)[update\_finding\_status](#tool-update_finding_status)[reorder\_findings](#tool-reorder_findings)

[Reports](#category-reports)[get\_report](#tool-get_report)[generate\_report\_pdf](#tool-generate_report_pdf)

[Schedules](#category-schedules)[list\_schedules](#tool-list_schedules)[get\_schedule](#tool-get_schedule)[create\_schedule](#tool-create_schedule)[update\_schedule](#tool-update_schedule)[delete\_schedule](#tool-delete_schedule)

[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.