Skip to main content

​
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: 
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 for details on generating and managing API keys.

​
Request format

Send request bodies as JSON with the Content-Type: application/json header: 
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: 
{
  "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: 
{
  "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: 
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Engagement not found",
    "statusCode": 404
  }
}
Common error codes:
HTTP StatusCodeDescription
400BAD_REQUESTThe request body or parameters are invalid
401UNAUTHORIZEDAPI key is missing or invalid
403FORBIDDENThe API key doesn’t have permission for this action
404NOT_FOUNDThe requested resource doesn’t exist
409CONFLICTA conflict with existing data (e.g., duplicate name)
422VALIDATION_ERRORRequest data failed validation
429RATE_LIMITEDRate limit exceeded
500INTERNAL_ERRORAn unexpected server error occurred

​
Rate limiting

API requests are rate-limited per API key. Rate limit headers are included in every response:
HeaderDescription
X-RateLimit-LimitTotal requests allowed per window
X-RateLimit-RemainingRequests remaining in the current window
X-RateLimit-ResetUnix 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.