API Introduction

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

Versioning

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

https://your-pwnbook-domain.com/api/v1/organizations

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/tasks
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "title": "Test login bypass",
  "description": "Attempt authentication bypass on the admin panel"
}

Response format

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

{
  "data": {
    "id": "tsk_01j9k2m3n4p5q6r7s8t9",
    "title": "Test login bypass",
    "status": "open",
    "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": "Resource 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 page-based pagination. Pass page and perPage query parameters:

GET /api/v1/tasks?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/tasks?status=open&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.

API Documentation

Core Endpoints

Overview

Base URL

Versioning

Authentication

Request format

Response format

Error responses

Rate limiting

Filtering and sorting

SDK support

​Overview

​Base URL

​Versioning

​Authentication

​Request format

​Response format

​Error responses

​Rate limiting

​Pagination

​Filtering and sorting

​SDK support

Overview

Base URL

Versioning

Authentication

Request format

Response format

Error responses

Rate limiting

Pagination

Filtering and sorting

SDK support