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 and Versioning

All API requests are made to:

https://turbopentest.com/api/v1

The API is versioned in the URL path. The current version is v1. When breaking changes are introduced, they will be released under a new version while the previous version remains available for a deprecation period.

Authentication

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

Authorization: Bearer tp_live_abc123def456

API Key Types

TurboPentest provides two types of API keys:

• Live keys (prefix tp_live_) — Full access to launch pentests, consume credits, and manage resources. Use in production systems.
• Test keys (prefix tp_test_) — Read-only access plus the ability to launch pentests in sandbox mode (no credits consumed, simulated results). Use during development.

API keys are scoped to an organization. You can create multiple keys with different permission levels in Settings > API Keys.

Rate Limits

The API enforces rate limits to ensure fair usage:

• Launch endpoints: 10 requests per minute
• Read endpoints: 60 requests per minute
• Webhook management: 30 requests per minute

Rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) are included in every response.

Core Endpoints

Launch a Pentest

POST /v1/pentests

{
  "target": "https://example.com",
  "tier": "standard",
  "options": {
    "source_url": "https://github.com/org/repo",
    "callback_url": "https://your-server.com/webhooks/turbopentest",
    "tags": ["sprint-42", "pre-release"],
    "phase1_tools": ["nmap", "zap", "nuclei", "ffuf"]
  }
}

Response (201 Created):

{
  "id": "pt_abc123",
  "status": "queued",
  "target": "https://example.com",
  "tier": "standard",
  "created_at": "2025-01-15T10:00:00Z",
  "estimated_duration": 2400
}

The phase1_tools option lets you select specific Phase 1 tools instead of running all 14. This reduces scan time when you only need specific reconnaissance data.

Check Pentest Status

GET /v1/pentests/{id}

Response:

{
  "id": "pt_abc123",
  "status": "phase2",
  "target": "https://example.com",
  "tier": "standard",
  "progress": {
    "phase1": "complete",
    "phase2_agents_complete": 5,
    "phase2_agents_total": 8,
    "findings_so_far": 7
  }
}

Status values progress through: queued > phase1 > phase2 > complete (or failed).

List Findings

GET /v1/pentests/{id}/findings?severity=high&category=injection

Response:

{
  "findings": [
    {
      "id": "f_xyz789",
      "title": "SQL Injection in /api/users",
      "severity": "high",
      "cvss": 8.6,
      "category": "A03:2021-Injection",
      "cwe": "CWE-89",
      "endpoint": "POST /api/users?sort=name",
      "agent": "web-app-agent",
      "status": "new",
      "retest_command": "docker run turbopentest/retest:sql-injection ...",
      "created_at": "2025-01-15T10:32:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20
}

Query parameters for filtering: severity, category, cwe, agent, status, page, per_page.

Get Finding Detail

GET /v1/findings/{id}

Returns the complete finding including proof-of-concept exploit, detailed remediation steps, exploit chain references, and retest commands.

Compare Pentests

GET /v1/pentests/compare?base={id1}&head={id2}

Returns findings categorized as new (in head but not base), fixed (in base but not head), or persistent (in both).

Pagination

List endpoints use cursor-based pagination for consistent results:

GET /v1/pentests?limit=10&cursor=eyJpZCI6InB0XzEyMyJ9

The response includes a next_cursor field. Pass it as the cursor parameter to fetch the next page. When next_cursor is null, you have reached the end.

Error Handling

The API returns standard HTTP status codes with descriptive error bodies:

{
  "error": {
    "code": "insufficient_credits",
    "message": "Your account does not have enough credits for a standard tier pentest. Required: 1, Available: 0.",
    "doc_url": "https://turbopentest.com/learn/api/errors#insufficient_credits"
  }
}

Common error codes:

• 400 — Invalid request parameters
• 401 — Invalid or missing API key
• 403 — API key lacks required permissions
• 404 — Resource not found
• 429 — Rate limit exceeded
• 402 — Insufficient credits

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 compliance 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

Webhook Subscriptions

Register webhook endpoints to receive push notifications instead of polling:

POST /v1/webhooks

{
  "url": "https://your-server.com/webhooks/turbopentest",
  "events": ["pentest.complete", "finding.discovered"],
  "secret": "whsec_your-signing-secret"
}

The secret is used to generate HMAC signatures for webhook verification.