REST API Reference
CTFFactory exposes a REST API that gives programmatic access to all major platform capabilities. Use the API to automate challenge generation, manage CTF events, retrieve analytics, and integrate CTFFactory into your existing toolchains.
Base URL
All API endpoints are relative to:
https://app.ctffactory.io/api/v1
Authentication
All requests must include a valid API key in the Authorization header:
Authorization: Bearer ctff_<your_api_key>
Requests without a valid key return 401 Unauthorized. Requests with a valid key that lacks the required scope return 403 Forbidden. See API Keys for instructions on creating and scoping keys.
Response Format
All responses are JSON. Successful responses use 2xx status codes. Error responses include a structured body:
{
"error": {
"code": "not_found",
"message": "The requested CTF event does not exist.",
"request_id": "req_01JXABCDE12345"
}
}
Paginated list endpoints return a data array and a pagination object:
{
"data": [ ... ],
"pagination": {
"page": 1,
"per_page": 25,
"total": 142,
"next_cursor": "cur_abc123"
}
}
Endpoint Reference
CTF Events
| Method | Path | Required Scope | Description |
|---|---|---|---|
GET |
/ctfs |
ctf:read |
List all CTF events in the workspace |
POST |
/ctfs |
ctf:write |
Create a new CTF event |
GET |
/ctfs/{ctf_id} |
ctf:read |
Retrieve a CTF event by ID |
PATCH |
/ctfs/{ctf_id} |
ctf:write |
Update CTF event settings |
DELETE |
/ctfs/{ctf_id} |
ctf:write |
Delete a CTF event (only if not deployed) |
POST |
/ctfs/{ctf_id}/deploy |
ctf:deploy |
Deploy a CTF event |
POST |
/ctfs/{ctf_id}/stop |
ctf:deploy |
Stop and tear down a running CTF instance |
Challenges
| Method | Path | Required Scope | Description |
|---|---|---|---|
GET |
/ctfs/{ctf_id}/challenges |
ctf:read |
List all challenges in a CTF |
POST |
/ctfs/{ctf_id}/challenges/generate |
ctf:write |
Generate a new challenge using AI |
GET |
/ctfs/{ctf_id}/challenges/{challenge_id} |
ctf:read |
Retrieve a specific challenge |
PATCH |
/ctfs/{ctf_id}/challenges/{challenge_id} |
ctf:write |
Update challenge content or settings |
DELETE |
/ctfs/{ctf_id}/challenges/{challenge_id} |
ctf:write |
Delete a challenge |
GET |
/ctfs/{ctf_id}/challenges/{challenge_id}/download |
ctf:read |
Download the player-only ZIP for non-deployable challenges |
Participants
| Method | Path | Required Scope | Description |
|---|---|---|---|
GET |
/ctfs/{ctf_id}/participants |
ctf:read |
List registered participants |
POST |
/ctfs/{ctf_id}/participants |
ctf:write |
Register a participant |
DELETE |
/ctfs/{ctf_id}/participants/{participant_id} |
ctf:write |
Remove a participant |
Scoreboard
| Method | Path | Required Scope | Description |
|---|---|---|---|
GET |
/ctfs/{ctf_id}/scoreboard |
ctf:read |
Retrieve the current scoreboard snapshot |
GET |
/ctfs/{ctf_id}/scoreboard/export |
ctf:read |
Export scoreboard as CSV |
Statistics and Analytics
| Method | Path | Required Scope | Description |
|---|---|---|---|
GET |
/ctfs/{ctf_id}/stats |
ctf:read |
Retrieve aggregate statistics (solve rates, solve times, category breakdown) |
GET |
/ctfs/{ctf_id}/stats/timeline |
ctf:read |
Score progression over time per team/participant |
Reports
| Method | Path | Required Scope | Description |
|---|---|---|---|
POST |
/ctfs/{ctf_id}/report |
ctf:read |
Generate a PDF/JSON report for the CTF event |
GET |
/reports/{report_id} |
ctf:read |
Check report generation status and retrieve download URL |
API Keys (Admin)
| Method | Path | Required Scope | Description |
|---|---|---|---|
GET |
/keys |
ctf:admin |
List all API keys in the workspace |
DELETE |
/keys/{key_id} |
ctf:admin |
Revoke any workspace API key |
Webhooks
| Method | Path | Required Scope | Description |
|---|---|---|---|
GET |
/webhooks |
ctf:admin |
List registered webhook endpoints |
POST |
/webhooks |
ctf:admin |
Register a new webhook endpoint |
PATCH |
/webhooks/{webhook_id} |
ctf:admin |
Update a webhook endpoint |
DELETE |
/webhooks/{webhook_id} |
ctf:admin |
Delete a webhook endpoint |
GET |
/webhooks/{webhook_id}/deliveries |
ctf:admin |
View webhook delivery history |
POST |
/webhooks/{webhook_id}/test |
ctf:admin |
Send a test event to the endpoint |
Versioning
The API is versioned via the URL path (/api/v1). CTFFactory maintains backward compatibility within a major version. Deprecation notices for removed or changed endpoints are announced at least 90 days in advance via the changelog and in-app notifications.
API Changelog
The API changelog is available at https://app.ctffactory.io/api/v1/changelog and lists additions, deprecations, and breaking changes by date.