Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/flagForgeCTF/flagForge/llms.txt

Use this file to discover all available pages before exploring further.

The FlagForge REST API lets you interact with challenges, flag submissions, leaderboards, and user data programmatically. All API routes are available under the /api/ path and return JSON responses. You can use the API from any HTTP client, including curl, fetch, or language-specific libraries.

​
Base URL

The hosted FlagForge instance is available at: 
https://flagforgectf.com
All API endpoints are rooted at /api/: 
https://flagforgectf.com/api/
If you are running a self-hosted instance, replace https://flagforgectf.com with your own domain throughout this reference.

​
Request format

Most endpoints accept JSON request bodies. Set the Content-Type header accordingly: 
Content-Type: application/json
Endpoints that accept file uploads (for example, creating a challenge with an attached file) use multipart/form-data instead. The individual endpoint pages note which format each route expects.

​
Response format

All responses return JSON. Successful responses include the requested data at the top level or nested under a named key (for example, data, pagination). Error responses include a message field describing what went wrong. 
{
  "message": "Missing required fields: title, points, category, flag, description"
}

​
Authentication

Most read endpoints are publicly accessible. Endpoints that create, update, or delete resources require you to be signed in. FlagForge uses session-based authentication via NextAuth — authentication state is carried by an HTTP cookie (next-auth.session-token) that NextAuth sets when you sign in. In a browser context, the cookie is sent automatically with every request. Admin-only endpoints additionally require that your account has the Admin role. See Authentication for details.

​
HTTP status codes

The API uses standard HTTP status codes to indicate the result of each request.
CodeMeaning
200 OKThe request succeeded.
201 CreatedA resource was created successfully.
400 Bad RequestThe request was missing required fields or contained invalid data.
401 UnauthorizedYou are not authenticated, or you do not have the required role.
403 ForbiddenYou are authenticated but do not have admin privileges for this route.
404 Not FoundThe requested resource does not exist.
410 GoneThe challenge has expired and is no longer available.
500 Internal Server ErrorAn unexpected error occurred on the server.

​
Pagination

GET /api/problems supports pagination and filtering through query parameters:
ParameterTypeDefaultDescription
pageinteger1The page number to retrieve.
limitinteger8The number of results per page.
categorystring—Filter by challenge category (e.g., Web, Crypto). Omit or pass All to return all categories.
Paginated responses include a pagination object: 
{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 8,
    "total": 42,
    "totalPages": 6,
    "hasNext": true,
    "hasPrev": false
  }
}
Example request with pagination and category filter: 
curl "https://flagforgectf.com/api/problems?page=2&limit=10&category=Web"

​
Explore the API

Authentication

Sign in with Google OAuth and pass authentication in API requests.

Challenges

List, retrieve, and create CTF challenges.

Flag submission

Submit flags and check whether a challenge has been solved.

Leaderboard

Fetch scores and rankings for all participants.

User profile

Retrieve user information, scores, and solved challenges.

Badges

List badge templates and retrieve badges awarded to users.

Admin

Admin-only routes for managing challenges, users, and badges.

Build docs developers (and LLMs) love

Get started for freeTalk to us