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

bash

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

json

{
  "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).

json

{
  "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).

json

{
  "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).

json

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

Environment Variables

Variable	Required	Description	Default
`APVISO_API_KEY`	Yes	API key starting with "apvk_". Generate one in Settings → API Keys.	None
`APVISO_API_URL`	No	Override 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

json

{}

Example Output

json

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

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

json

{}

Example Output

json

{
  "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

Name	Type	Description
`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

json

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

Example Output

json

{
  "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

Name	Type	Description
`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

json

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

Example Output

json

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

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

Name	Type	Description
`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

json

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

Example Output

json

{
  "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

Name	Type	Description
`targetId`required	`string`	UUIDv7 identifier of the target.

Returns

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

Example Input

json

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

Example Output

json

{
  "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

Name	Type	Description
`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

json

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

Example Output

json

{
  "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

Name	Type	Description
`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

json

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

Example Output

json

{
  "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

Name	Type	Description
`targetId`required	`string`	UUIDv7 identifier of the target.

Returns

Empty compatibility payload with deprecated=true.

Example Input

json

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

Example Output

json

{
  "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

Name	Type	Description
`targetId`required	`string`	UUIDv7 identifier of the target to delete.

Returns

Confirmation message on success.

Example Input

json

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

Example Output

json

{
  "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

Name	Type	Description
`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

json

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

Example Output

json

{
  "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

Name	Type	Description
`scanId`required	`string`	UUIDv7 identifier of the pentest.

Returns

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

Example Input

json

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

Example Output

json

{
  "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

Name	Type	Description
`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

json

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

Example Output

json

{
  "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

Name	Type	Description
`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

json

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

Example Output

json

{
  "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

Name	Type	Description
`scanId`required	`string`	UUIDv7 identifier of the scan to cancel.

Returns

Updated scan status.

Example Input

json

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

Example Output

json

{
  "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

Name	Type	Description
`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

json

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

Example Output

json

{
  "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

Name	Type	Description
`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

json

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

Example Output

json

{
  "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

Name	Type	Description
`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

json

{
  "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

json

{
  "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

Name	Type	Description
`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

json

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

Example Output

json

{
  "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

Name	Type	Description
`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

json

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

Example Output

json

{
  "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

json

{}

Example Output

json

{
  "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

Name	Type	Description
`scheduleId`required	`string`	UUIDv7 identifier of the schedule.

Returns

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

Example Input

json

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

Example Output

json

{
  "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

Name	Type	Description
`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

json

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

Example Output

json

{
  "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

Name	Type	Description
`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

json

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

Example Output

json

{
  "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

Name	Type	Description
`scheduleId`required	`string`	UUIDv7 identifier of the schedule to delete.

Returns

Confirmation message on success.

Example Input

json

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

Example Output

json

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

Back to Knowledge Base