> ## Documentation Index
> Fetch the complete documentation index at: https://pentest-tools.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API overview

> Programmatic access to Pentest-Tools.com capabilities

## Introduction

The Pentest-Tools.com REST API lets you manage targets, run scans, retrieve findings, and generate reports programmatically.

Use it to integrate security scanning into your existing tools and workflows.

## What you can do

<CardGroup cols={2}>
  <Card title="Targets" icon="crosshairs">
    View all targets from a workspace, get details for one, or create new targets.
  </Card>

  <Card title="Scans" icon="radar">
    Start scans, stop them, get status updates, or retrieve full scan results.
  </Card>

  <Card title="Workspaces" icon="folder-tree">
    Get details for all workspaces, view a specific one, or create new ones.
  </Card>

  <Card title="Findings" icon="flag">
    Access vulnerability findings and their details.
  </Card>

  <Card title="Reports" icon="file-pdf">
    Generate and download reports in PDF, DOCX, HTML, JSON, CSV, or XLSX format.
  </Card>

  <Card title="And More" icon="ellipsis">
    HTTP loggers, VPN profiles, wordlists, and finding templates.
  </Card>
</CardGroup>

## API base URL

```text theme={null}
https://api.pentest-tools.com/api/v2
```

<Note>
  This is the recommended base URL. It automatically routes requests to your account's region based on your API key, so the same URL works no matter where your account lives.

  You can also call your region directly if you prefer: `https://app-us.pentest-tools.com/api/v2` (US) or `https://app.pentest-tools.com/api/v2` (Europe).
</Note>

## Quick start

### 1. Get your API key

Generate an API key from **My account > API** in the web application.

<Info>
  API access requires a plan that includes it. Check your plan details if you receive a 403 error.
</Info>

### 2. Make your first request

```bash theme={null}
curl -X GET "https://api.pentest-tools.com/api/v2/targets" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### 3. Start a scan

```bash theme={null}
curl -X POST "https://api.pentest-tools.com/api/v2/scans" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool_id": 170, "target_name": "https://example.com"}'
```

## Available endpoints

| Resource          | Endpoint                    | Operations                                |
| ----------------- | --------------------------- | ----------------------------------------- |
| Targets           | `/targets`                  | List, create, get, delete                 |
| Scans             | `/scans`                    | List, start, get, stop, delete            |
| Scan Output       | `/scans/{id}/output`        | Get JSON results                          |
| Scan Raw Output   | `/scans/{id}/raw`           | Get raw output                            |
| Findings          | `/findings`                 | List, get details, screenshots            |
| Workspaces        | `/workspaces`               | List, create, get, update, delete         |
| Reports           | `/reports`                  | List, create, get, download, delete       |
| HTTP Loggers      | `/http_loggers`             | List, create, get, delete, get/clear data |
| VPN Profiles      | `/vpn_profiles`             | List                                      |
| Wordlists         | `/wordlists`                | List, get, delete, get contents           |
| Finding Templates | `/public/finding_templates` | List (public)                             |

## Response format

Most successful responses return JSON with data wrapped in a `data` field:

```json theme={null}
{
  "data": {
    "id": 12345,
    "name": "example.com",
    "status": "finished"
  }
}
```

For list endpoints, the response includes an array:

```json theme={null}
{
  "data": [
    { "id": 1, "name": "target1.com" },
    { "id": 2, "name": "target2.com" }
  ]
}
```

<Note>
  Three endpoints skip the `data` wrapper and return raw content: `GET /reports/{id}/download` streams the report file, `GET /scans/{id}/output` with `Accept: application/pdf` returns a PDF, and `GET /scans/{id}/raw` with `Accept: text/plain` returns plain text.
</Note>

<Note>
  Error responses use a different format. See [Limits and Errors](/docs/api-reference/limits-and-errors) for details.
</Note>

## Rate limits

API requests are rate limited per user:

| Request Type         | Limit      |
| -------------------- | ---------- |
| GET requests         | 250/minute |
| POST/DELETE requests | 125/minute |
| `/scans/{id}/output` | 60/minute  |

See [Limits and Errors](/docs/api-reference/limits-and-errors) for full details.

## OpenAPI schema

This API reference is based on our public OpenAPI schema, available at:

```text theme={null}
https://api.pentest-tools.com/api-schema.yml
```

You can use this schema with tools like Postman, Insomnia, or code generators.

## Support

If you have questions about the API, contact us at [support@pentest-tools.com](mailto:support@pentest-tools.com).

## Next steps

* [Authentication](/docs/api-reference/authentication): Get your API key and authenticate requests
* [API examples](/docs/api-reference/examples): Python examples for common workflows
* [Limits and errors](/docs/api-reference/limits-and-errors): Rate limits and error handling