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

# API Introduction

> The Pwnbook REST API lets you integrate Pwnbook into your security workflows, automate engagement management, and build custom tooling on top of the platform.

## Overview

The Pwnbook API is a RESTful HTTP API. All requests and responses use JSON. The API is designed to be predictable and consistent — once you understand the patterns used by one endpoint, you'll find the others work the same way.

## Base URL

All API endpoints are relative to your Pwnbook instance's base URL:

```
https://your-pwnbook-domain.com/api
```

For the Pwnbook cloud service:

```
https://app.pwnbook.io/api
```

## Versioning

The current API version is `v1`. All endpoints are prefixed with `/api/v1/`:

```
https://app.pwnbook.io/api/v1/engagements
```

The API version is included in all request paths. When breaking changes are introduced, a new version is released with an updated path prefix, and the previous version remains supported for a deprecation period.

## Authentication

All API requests must be authenticated using an API key. Include your API key in the `Authorization` header:

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

API keys are scoped to an organization and carry the permissions defined when the key was created. See [API Authentication](/api-reference/authentication) for details on generating and managing API keys.

## Request format

Send request bodies as JSON with the `Content-Type: application/json` header:

```http theme={null}
POST /api/v1/engagements
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "name": "Acme Corp External Assessment",
  "description": "Q1 2025 external network penetration test"
}
```

## Response format

All responses are JSON objects. Successful responses include a `data` field containing the response payload:

```json theme={null}
{
  "data": {
    "id": "eng_01j9k2m3n4p5q6r7s8t9",
    "name": "Acme Corp External Assessment",
    "description": "Q1 2025 external network penetration test",
    "status": "active",
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-01-15T10:30:00.000Z"
  }
}
```

List responses include pagination metadata:

```json theme={null}
{
  "data": [...],
  "meta": {
    "total": 42,
    "page": 1,
    "perPage": 20,
    "totalPages": 3
  }
}
```

## Error responses

Error responses use standard HTTP status codes and include a JSON body with details:

```json theme={null}
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Engagement not found",
    "statusCode": 404
  }
}
```

Common error codes:

| HTTP Status | Code               | Description                                          |
| ----------- | ------------------ | ---------------------------------------------------- |
| 400         | `BAD_REQUEST`      | The request body or parameters are invalid           |
| 401         | `UNAUTHORIZED`     | API key is missing or invalid                        |
| 403         | `FORBIDDEN`        | The API key doesn't have permission for this action  |
| 404         | `NOT_FOUND`        | The requested resource doesn't exist                 |
| 409         | `CONFLICT`         | A conflict with existing data (e.g., duplicate name) |
| 422         | `VALIDATION_ERROR` | Request data failed validation                       |
| 429         | `RATE_LIMITED`     | Rate limit exceeded                                  |
| 500         | `INTERNAL_ERROR`   | An unexpected server error occurred                  |

## Rate limiting

API requests are rate-limited per API key. Rate limit headers are included in every response:

| Header                  | Description                                      |
| ----------------------- | ------------------------------------------------ |
| `X-RateLimit-Limit`     | Total requests allowed per window                |
| `X-RateLimit-Remaining` | Requests remaining in the current window         |
| `X-RateLimit-Reset`     | Unix timestamp when the rate limit window resets |

When you exceed the rate limit, you'll receive a `429 Too Many Requests` response. Implement exponential backoff and retry logic in your client.

## Pagination

List endpoints support cursor-based and page-based pagination. Pass `page` and `perPage` query parameters:

```
GET /api/v1/engagements?page=2&perPage=20
```

Default `perPage` is 20. Maximum `perPage` is 100.

## Filtering and sorting

Most list endpoints support filtering and sorting via query parameters:

```
GET /api/v1/engagements?status=active&sort=createdAt&order=desc
```

Refer to individual endpoint documentation for supported filter and sort fields.

## SDK support

Currently, direct HTTP requests are the primary integration method. Community-maintained SDKs may be available — check the Pwnbook GitHub organization for the latest.