Endpoints
| Method | Path | Description |
|---|
GET | /api/v1/engagements | List all engagements |
POST | /api/v1/engagements | Create a new engagement |
GET | /api/v1/engagements/:id | Get a single engagement |
PATCH | /api/v1/engagements/:id | Update an engagement |
DELETE | /api/v1/engagements/:id | Delete an engagement |
POST | /api/v1/engagements/:id/archive | Archive an engagement |
POST | /api/v1/engagements/:id/unarchive | Unarchive an engagement |
List engagements
Returns a paginated list of engagements belonging to the organization.
GET /api/v1/engagements
Authorization: Bearer YOUR_API_KEY
Query parameters
| Parameter | Type | Description |
|---|
status | string | Filter by status: active or archived |
page | integer | Page number (default: 1) |
perPage | integer | Results per page (default: 20, max: 100) |
sort | string | Sort field: createdAt, updatedAt, name |
order | string | Sort order: asc or desc (default: desc) |
Example request
curl "https://app.pwnbook.io/api/v1/engagements?status=active&perPage=10" \
-H "Authorization: Bearer pwbk_live_abc123..."
Example response
{
"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-20T14:15:00.000Z"
},
{
"id": "eng_02j9k2m3n4p5q6r7s8t9",
"name": "Globex Internal Network Review",
"description": "Internal segmentation assessment",
"status": "active",
"createdAt": "2025-01-10T09:00:00.000Z",
"updatedAt": "2025-01-18T16:45:00.000Z"
}
],
"meta": {
"total": 2,
"page": 1,
"perPage": 10,
"totalPages": 1
}
}
Create an engagement
Creates a new engagement in the organization.
Required scope: engagements:write
POST /api/v1/engagements
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Request body
| Field | Type | Required | Description |
|---|
name | string | Yes | Engagement name |
description | string | No | Optional description |
Example request
curl -X POST "https://app.pwnbook.io/api/v1/engagements" \
-H "Authorization: Bearer pwbk_live_abc123..." \
-H "Content-Type: application/json" \
-d '{
"name": "Omega Corp Web Application Pentest",
"description": "Black-box assessment of the customer portal"
}'
Example response
{
"data": {
"id": "eng_03j9k2m3n4p5q6r7s8t9",
"name": "Omega Corp Web Application Pentest",
"description": "Black-box assessment of the customer portal",
"status": "active",
"createdAt": "2025-03-01T08:00:00.000Z",
"updatedAt": "2025-03-01T08:00:00.000Z"
}
}
Get an engagement
Retrieves a single engagement by ID.
Required scope: engagements:read
GET /api/v1/engagements/:id
Authorization: Bearer YOUR_API_KEY
Example request
curl "https://app.pwnbook.io/api/v1/engagements/eng_03j9k2m3n4p5q6r7s8t9" \
-H "Authorization: Bearer pwbk_live_abc123..."
Example response
{
"data": {
"id": "eng_03j9k2m3n4p5q6r7s8t9",
"name": "Omega Corp Web Application Pentest",
"description": "Black-box assessment of the customer portal",
"status": "active",
"createdAt": "2025-03-01T08:00:00.000Z",
"updatedAt": "2025-03-01T08:00:00.000Z"
}
}
Update an engagement
Updates one or more fields of an existing engagement.
Required scope: engagements:write
PATCH /api/v1/engagements/:id
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Request body
| Field | Type | Required | Description |
|---|
name | string | No | New engagement name |
description | string | No | New description |
Example request
curl -X PATCH "https://app.pwnbook.io/api/v1/engagements/eng_03j9k2m3n4p5q6r7s8t9" \
-H "Authorization: Bearer pwbk_live_abc123..." \
-H "Content-Type: application/json" \
-d '{
"description": "Black-box + grey-box assessment of the customer portal"
}'
Archive an engagement
Archives an active engagement. Archived engagements are read-only.
Required scope: engagements:write
POST /api/v1/engagements/:id/archive
Authorization: Bearer YOUR_API_KEY
Example request
curl -X POST "https://app.pwnbook.io/api/v1/engagements/eng_03j9k2m3n4p5q6r7s8t9/archive" \
-H "Authorization: Bearer pwbk_live_abc123..."
Example response
{
"data": {
"id": "eng_03j9k2m3n4p5q6r7s8t9",
"status": "archived",
"updatedAt": "2025-03-15T17:00:00.000Z"
}
}
Delete an engagement
Permanently deletes an engagement and all its associated data. This action cannot be undone.
Required scope: engagements:delete
DELETE /api/v1/engagements/:id
Authorization: Bearer YOUR_API_KEY
Example request
curl -X DELETE "https://app.pwnbook.io/api/v1/engagements/eng_03j9k2m3n4p5q6r7s8t9" \
-H "Authorization: Bearer pwbk_live_abc123..."
Example response
{
"data": {
"deleted": true,
"id": "eng_03j9k2m3n4p5q6r7s8t9"
}
}
Deleting an engagement is irreversible. All targets, tasks, wiki pages, reports, threat models, and API requests belonging to the engagement are permanently removed.
