API-Driven Pentesting

The TurboPentest REST API

Every action you can perform in the TurboPentest dashboard is also available through the REST API. This enables fully programmatic security testing - you can build custom integrations, automate complex workflows, and embed pentesting into any system that can make HTTP requests.

The API follows RESTful conventions with JSON request and response bodies, predictable resource URLs, and standard HTTP status codes.

Base URL

All API requests are made to:

https://turbopentest.com/api

Authentication

The API uses bearer token authentication. Include your API key in the Authorization header of every request:

Authorization: Bearer tp_abc123def456

API Keys

All TurboPentest API keys start with the tp_ prefix. Create keys in Settings > API Keys. The full key is shown only once at creation - TurboPentest stores a SHA-256 hash, not the key itself, so copy it immediately. Each key has full access to your account: it can launch pentests and consume credits, so treat it like a password. You can create multiple named keys (one per integration) and revoke any key individually if it is compromised.

Rate Limits

The API enforces rate limits to ensure fair usage:

• Pentest launch endpoint (POST /api/pentests): 5 requests per minute
• Read endpoints: 200 requests per minute

When a limit is exceeded, the API returns HTTP 429 with a Retry-After header indicating how many seconds to wait before retrying.

Core Endpoints

Launch a Pentest

POST /api/pentests

{
  "targetUrl": "https://example.com",
  "tier": "standard",
  "repoUrl": "https://github.com/org/repo",
  "notes": "Focus on the /api/* endpoints. Staging credentials in scope."
}

Response (201 Created): the created pentest object, including its id, status (queued), targetUrl, and timestamps.

Key request fields:

• targetUrl (required for single-target runs) - The URL to pentest. The domain must already be verified in your account, or the API returns 403.
• targetUrls (optional) - An array of up to 20 URLs for a multi-domain launch. One credit is consumed per target, and overflow beyond available capacity is queued automatically.
• tier (optional) - recon, standard, deep, or blitz. The API consumes your oldest available credit of that tier; if omitted, the oldest available credit of any tier is used.
• repoUrl (optional) - A GitHub repository URL. Enables the white-box tools (gitleaks, semgrep, grype) using your GitHub App connection.
• notes (optional) - Scoping notes passed to the AI agents.
• credentials (optional) - Test credentials, stored encrypted and purged after the run.

A maximum of 5 pentests can be active per account at once, and only one active pentest is allowed per target.

Check Pentest Status

GET /api/pentests/{id}

The response includes the pentest's status, tool results, findings so far, and the executive summary once complete. Status values progress through: queued > scanning > complete (or failed). A pentest that is waiting for infrastructure capacity shows capacity_queued and launches automatically when capacity frees up.

List Pentests

GET /api/pentests?status=complete&search=example.com

Returns all of your pentests, newest first, with pre-computed severity counts per pentest. Optional query parameters: status (queued, capacity_queued, scanning, complete, failed) and search (matches the target URL).

Download a Report

GET /api/pentests/{id}/report?format=pdf

Supported formats include pdf, json, and markdown (plus exchange formats for tools like Dradis and AttackForge). JSON and markdown are the most convenient for programmatic processing.

Finding Continuity

There is no separate compare endpoint - TurboPentest computes continuity automatically. When a pentest completes against a target you have tested before, each finding is fingerprinted and matched against the previous run, and its continuity status is set to new, confirmed, persistent, or fixed. The finding objects returned by GET /api/pentests/{id} include the fingerprint and continuity fields, so a custom integration can also diff two runs itself by matching fingerprints.

Error Handling

The API returns standard HTTP status codes with a JSON error message:

{
  "error": "No credits available. Purchase a pentest or subscription first."
}

Common error codes:

• 400 - Invalid request parameters
• 401 - Invalid or missing API key
• 402 - No credits available
• 403 - Domain not verified, or safe harbor agreement not accepted
• 409 - A pentest for this target is already running (or a duplicate submission)
• 429 - Rate limit exceeded, or too many active pentests (max 5)

Building Custom Integrations

The REST API enables integrations beyond the built-in Slack and Jira options. Common custom integrations include:

• Custom dashboards - Aggregate pentest results across multiple projects into a single internal dashboard
• Compliance automation - Generate audit evidence by querying pentest history and finding status
• Chat ops - Build custom Slack/Teams/Discord bots that launch pentests from chat commands
• CI/CD systems - Integrate with Jenkins, GitLab CI, Bitbucket Pipelines, or any CI system beyond GitHub Actions
• Security orchestration - Feed TurboPentest findings into SIEM or SOAR platforms

Detecting Completion

The API does not currently push webhooks for pentest events, so integrations should poll for completion:

1. Launch with POST /api/pentests and record the returned id.
2. Poll GET /api/pentests/{id} on an interval (the official GitHub Action polls every 30 seconds).
3. Stop when status is complete or failed, then fetch findings or download the report.

Polling at 30-60 second intervals stays comfortably within the read rate limit. For push-style notifications to humans, configure the Slack integration alongside your API workflow.