API reference

rCTF exposes a JSON REST API under /api. The @rctf/types package exports the route definitions and TypeScript types used by both the server and API clients.

Versions

rCTF serves V1 and V2 together:

Use V2 when it provides the operation you need. Some operations still exist only in V1. Routes shared by both versions usually return the same response kind, with V2 adding fields such as avatars, country codes, and blood indices.

Typed route contract

The @rctf/types package exports the public route definitions, responses, enums, and helper types:

import {
  GetChallengesRouteV2,
  type RouteBodyInput,
  type RouteQueryInput,
  type RouteSuccessResponse,
} from '@rctf/types'

type Query = RouteQueryInput<typeof GetChallengesRouteV2>
type Response = RouteSuccessResponse<typeof GetChallengesRouteV2>

RouteBodyInput<T>, RouteQueryInput<T>, and RouteParamsInput<T> provide the input types for the body, query string, and path parameters. They describe values before the server applies Zod conversions.

Authentication

User-authenticated routes require an auth token in the Authorization header:

Authorization: Bearer <auth-token>

Admin bot service routes use the same header with the shared secret from adminBot.provider.options.secretKey instead of a user token.

Token types

Tokens are encrypted with AES-GCM using the configured tokenKey. Changing tokenKey invalidates every token that was issued before the rotation.

Response format

Most API responses wrap their fields in the following object:

1
{
2
  "kind": "goodChallenges",
3
  "message": "The retrieval of challenges was successful.",
4
  "data": []
5
}

Responses without additional data omit the data field:

1
{
2
  "kind": "goodFlag",
3
  "message": "The flag is correct."
4
}

One typed route does not use this wrapper. GET /api/v1/integrations/ctftime/leaderboard returns { "standings": [...] } directly.

Request validation

Routes with a JSON body parse JSON, while upload routes parse multipart/form-data. Invalid input returns 400 badBody with a machine-readable reason:

1
{
2
  "kind": "badBody",
3
  "message": "The request body does not meet requirements.",
4
  "data": {
5
    "reason": "query:limit: Too small: expected number to be >=1"
6
  }
7
}

The reason begins with body, query, or params to identify the source. Malformed JSON returns 400 badJson. Malformed form data returns 400 badBody with body:formData:malformed.

Permissions

Admin routes use bitmask permissions from Permissions:

When a route lists multiple permission bits, the user needs all of them.

Timing gates

Routes marked as start-gated return 401 badNotStarted before startTime. Admin users can bypass that gate when the route defines a bypass permission and their token has the required bit.

POST /api/v1/challs/:id/submit is also end-gated, returning 401 badEnded after endTime.

Captcha

Captcha is checked only for actions listed in the provider’s protected actions. V1 request bodies use recaptchaCode. V2 uses captchaCode.

Rate limits

Rate-limited routes return 429 badRateLimit with data.timeLeft, measured in milliseconds:

Registration uses its buckets only when rCTF would send a verification email. Recovery checks its buckets before looking up the account, so its rate-limit behavior does not reveal whether an email is registered. Both limits apply even when captcha is enabled.

Route sections