Challenges

Challenge listing, solve listing, flag submission, and dynamic-scoring webhook routes.

Challenge routes provide public challenge metadata, solve history, the legacy flag submission endpoint, and the dynamic-scoring webhook. Admin challenge mutation routes are documented in Admin.

For new clients, prefer V2 routes. V1 routes remain available for older clients. Flag submission still uses V1 because there is no V2 route for that action.

Scoring behavior#

Challenge point values come from the configured scoring provider for decay challenges. The public challenge list returns the current point value. It does not expose the configured points.min or points.max range. Challenge updates and solve changes trigger leaderboard recalculation.

dynamic challenges receive per-team scores over a webhook instead - see Submit dynamic scores for the wire format and Scoring for the operator-facing model.

Visibility behavior#

Regular users see challenges once those challenges are visible and released. Admin users with challsRead can read through the CTF start gate with the same public routes. Hidden and scheduled release rules still apply inside the challenge service.

`GET` Challenge list

GET /api/[v2,v1]/challs

$curl -sS "https://rctf-new-dev.es3n1n.io/api/v2/challs" \
  -H "Authorization: Bearer <auth-token>"

{
  "kind": "goodChallengesV2",
  "message": "The retrieval of challenges was successful.",
  "data": [
    {
      "id": "<id>",
      "name": "baby-rev",
      "description": "A small reverse engineering challenge.",
      "category": "rev",
      "author": "es3n1n",
      "files": [
        {
          "name": "chall.zip",
          "url": "<url>",
          "size": 0
        }
      ],
      "points": 487,
      "solves": 12,
      "sortWeight": 0,
      "instancerLifetime": 0,
      "instancerExtendable": false,
      "adminBotInputs": {
        "url": {
          "pattern": "^https?://",
          "flags": "i"
        }
      },
      "hasFlag": true,
      "scoringKind": "decay",
      "yourScore": 0,
      "yourPointDelta": 0
    }
  ]
}

{
  "kind": "badNotStarted",
  "message": "The CTF has not started yet."
}

$curl -sS "https://rctf-new-dev.es3n1n.io/api/v1/challs"

{
  "kind": "goodChallenges",
  "message": "The retrieval of challenges was successful.",
  "data": [
    {
      "id": "<id>",
      "name": "baby-rev",
      "description": "A small reverse engineering challenge.",
      "category": "rev",
      "author": "es3n1n",
      "files": [
        {
          "name": "chall.zip",
          "url": "<url>"
        }
      ],
      "points": 487,
      "solves": 12,
      "sortWeight": 0
    }
  ]
}

{
  "kind": "badNotStarted",
  "message": "The CTF has not started yet."
}

Auth: Optional
Gate: Started (bypass challsRead)
Permissions: No extra permissions
Captcha: No captcha
Rate limit: No rate limit

Returns the challenge list visible to the current request. Regular users do not receive hidden challenges or challenges with a future releaseTime.

For new clients, prefer V2. It adds instancer metadata, admin bot input schemas, and the hasFlag field. V1 remains available for older clients and returns the original challenge fields.

Response fields

idstring

Challenge ID.

namestring

Display name.

descriptionstring

Markdown challenge description.

categorystring

Category name.

authorstring

Author display name.

files[].namestring

File name.

files[].urlstring

Download URL.

files[].sizenumber | null

File size in bytes.

pointsnumber

Current score after dynamic scoring.

solvesnumber

Current solve count.

sortWeightnumber | null

Optional ordering weight.

instancerLifetimenumber | null

Instance timeout in milliseconds when the challenge has instancer config and an instancer is enabled.

instancerExtendableboolean

false only when challenge config explicitly disables extension.

adminBotInputsRecord<string, { pattern: string, flags?: string }> | null | undefined

Participant input schema for admin-bot challenges.

hasFlagboolean

Whether the challenge has a flag configured.

scoringKind"decay" | "dynamic" | undefined

Scoring kind: decay, static, or dynamic.

yourScorenumber | undefined

Caller's current points for this challenge. Present when the user has a solve (or feed entry) for it.

yourPointDeltanumber | undefined

Caller's latest dynamic point delta for this challenge. Present for dynamic challenges when the caller had an entry in the latest feed tick.

Response fields

idstring

Challenge ID.

namestring

Display name.

descriptionstring

Markdown challenge description.

categorystring

Category name.

authorstring

Author display name.

files[].namestring

File name.

files[].urlstring

Download URL.

pointsnumber

Current score after dynamic scoring.

solvesnumber

Current solve count.

sortWeightnumber | null | undefined

Optional ordering weight.

`GET` Challenge solves

GET /api/[v2,v1]/challs/:id/solves

$curl -sS "https://rctf-new-dev.es3n1n.io/api/v2/challs/<id>/solves?limit=100&offset=0" \
  -H "Authorization: Bearer <auth-token>"

{
  "kind": "goodChallengeSolves",
  "message": "The challenges solves have been retrieved.",
  "data": {
    "solves": [
      {
        "id": "solve-a1b2c3",
        "createdAt": 1710000000000,
        "userId": "team-xyz",
        "userName": "otter-sec",
        "userAvatarUrl": "https://cdn.example.com/avatar.png",
        "userCountryCode": "US",
        "userStatusText": "ATB",
        "globalPlace": 3,
        "division": "open",
        "divisionPlace": 1,
        "bloodIndex": 0
      }
    ],
    "mySolvePosition": 12
  }
}

{
  "kind": "badNotStarted",
  "message": "The CTF has not started yet."
}

{
  "kind": "badChallenge",
  "message": "The challenge could not be found."
}

{
  "kind": "badBody",
  "message": "The request body does not meet requirements.",
  "data": {
    "reason": "<reason>"
  }
}

$curl -sS "https://rctf-new-dev.es3n1n.io/api/v1/challs/<id>/solves?limit=100&offset=0"

{
  "kind": "goodChallengeSolves",
  "message": "The challenges solves have been retreived.",
  "data": {
    "solves": [
      {
        "id": "solve-a1b2c3",
        "createdAt": 1710000000000,
        "userId": "team-xyz",
        "userName": "otter-sec"
      }
    ]
  }
}

{
  "kind": "badNotStarted",
  "message": "The CTF has not started yet."
}

{
  "kind": "badChallenge",
  "message": "The challenge could not be found."
}

{
  "kind": "badBody",
  "message": "The request body does not meet requirements.",
  "data": {
    "reason": "<reason>"
  }
}

Auth: Optional
Gate: Started (bypass challsRead)
Permissions: No extra permissions
Captcha: No captcha
Rate limit: No rate limit

Returns a page of solve history for one challenge.

V2 includes solve avatars, country codes, division placements, blood index, and the authenticated user’s mySolvePosition when optional auth is present. V1 remains available for older clients and returns a smaller solve row.

Path parameters

id
*
 required

string

Challenge ID.

Query parameters

limit
*
 required

number

Integer >= 1. Maximum enforced by config.

offset
*
 required

number

Integer >= 0.

Response fields

solves[].idstring

Solve ID.

solves[].createdAtnumber

Unix timestamp in milliseconds.

solves[].userIdstring

Team ID.

solves[].userNamestring

Team display name.

solves[].userAvatarUrlstring | null

Avatar URL when set.

solves[].userCountryCodestring | null

ISO country code when set.

solves[].userStatusTextstring | null

Status text when set.

solves[].globalPlacenumber

Team's current global standing at solve time.

solves[].divisionstring

Team division at solve time.

solves[].divisionPlacenumber

Team's current divisional standing at solve time.

solves[].bloodIndexnumber | null

0, 1, or 2 for the first three solves. Otherwise null.

mySolvePositionnumber | null

Authenticated user's solve position. Present when optional auth is sent.

Response fields

solves[].idstring

Solve ID.

solves[].createdAtnumber

Unix timestamp in milliseconds.

solves[].userIdstring

Team ID.

solves[].userNamestring

Team display name.

`POST` Submit a flag

POST /api/v1/challs/:id/submit

$curl -sS "https://rctf-new-dev.es3n1n.io/api/v1/challs/<id>/submit" \
  -H "Authorization: Bearer <auth-token>" \
  --json '{
    "flag": "flag{example}"
  }'

{
  "kind": "goodFlag",
  "message": "The flag is correct."
}

{
  "kind": "badFlag",
  "message": "The flag was incorrect."
}

{
  "kind": "badPerms",
  "message": "The user does not have the required permissions."
}

{
  "kind": "badNotStarted",
  "message": "The CTF has not started yet."
}

{
  "kind": "badEnded",
  "message": "The CTF has ended."
}

{
  "kind": "badChallenge",
  "message": "The challenge could not be found."
}

{
  "kind": "badRateLimit",
  "message": "You are trying this too fast.",
  "data": {
    "timeLeft": 0
  }
}

{
  "kind": "badAlreadySolvedChallenge",
  "message": "The flag was already submitted."
}

{
  "kind": "badUnknownUser",
  "message": "The user does not exist."
}

{
  "kind": "badToken",
  "message": "The token provided is invalid."
}

{
  "kind": "badJson",
  "message": "The request JSON body is malformed."
}

{
  "kind": "badBody",
  "message": "The request body does not meet requirements.",
  "data": {
    "reason": "<reason>"
  }
}

Auth: Required
Gate: Started + Before end (bypass challsWrite)
Permissions: No extra permissions
Captcha: No captcha
Rate limit: Burst 5, refill window 25000 ms, scoped to user and challenge.

Submits a flag for the authenticated team. This route uses V1 because there is no V2 equivalent.

Rate limit conventions are documented under /api#rate-limits.

Path parameters

id
*
 required

string

Challenge ID.

Request body

flag
*
 required

string

Maximum length 1024.

A correct flag returns 200 goodFlag (no data) and records a solve for the team. The route records a submission audit row for both correct and incorrect attempts. Admins can read those rows through /api/v2/admin/submissions.

`POST` Submit dynamic scores

POST /api/v2/challs/:id/scores

$curl -sS "https://rctf-new-dev.es3n1n.io/api/v2/challs/challenge-id/scores" \
  -H "Authorization: Bearer <auth-token>" \
  --json '{
    "scores": [
      {
        "userId": "11111111-2222-3333-4444-555555555555",
        "points": 1280
      },
      {
        "userId": "66666666-7777-8888-9999-000000000000",
        "points": 940
      }
    ]
  }'

{
  "kind": "goodDynamicScores",
  "message": "Scores accepted.",
  "data": {
    "inserted": 0,
    "updated": 0,
    "deleted": 0
  }
}

{
  "kind": "badSignature",
  "message": "Invalid HMAC signature or timestamp."
}

{
  "kind": "badBody",
  "message": "The request body does not meet requirements.",
  "data": {
    "reason": "<reason>"
  }
}

{
  "kind": "badJson",
  "message": "The request JSON body is malformed."
}

Auth: Service
Gate: None
Permissions: No extra permissions
Captcha: No captcha
Rate limit: No rate limit

Publishes per-team scores for a dynamic challenge. The endpoint is authenticated through an HMAC signature derived from the challenge’s per-instance webhook secret (the scoring.source.secret value set on the challenge); no user auth token is involved. The operator guide for this endpoint, including the team-identifier patterns and the recommended publisher snippet, lives at Scoring.

Warning (No event-timing gate)

This route deliberately has neither onlyWhenStarted nor onlyWhenNotFinished. Backends can seed scores before startTime and any deliveries that land after endTime are still applied to the final tally. Cutting the feed off cleanly at end is the operator’s job.

Authentication#

Header	Value
`X-RCTF-Timestamp`	Unix milliseconds at signing time. Must be within a five-minute skew window of the server clock.
`X-RCTF-Signature`	`sha256=` followed by the lowercase hex HMAC-SHA256 of `${timestamp}.${raw_body}` using the challenge’s webhook `secret`.

Sign the raw request bytes, not the re-serialized JSON. Any difference between the signed bytes and the bytes on the wire (whitespace, key ordering, middleware re-serialization) will fail verification.

Unknown challenge IDs, non-dynamic challenges, mismatched signatures, and timestamps outside the skew window all return the same 401 badSignature so the endpoint can’t be probed for which challenges accept a feed.

Path parameters

id
*
 required

string

Challenge ID.

Request body

scores
*
 required

object[]

Request body field for scores.

Each entry is an absolute setter for that team and challenge. A points value of 0 clears the team’s score for the challenge, negative values are accepted, and teams omitted from the payload keep whatever score they already had. Entries for team IDs that don’t exist are silently dropped - the response counts only reflect rows that actually landed.

Response fields

insertednumber

Returned inserted value.

updatednumber

Returned updated value.

deletednumber

Returned deleted value.

Successful pushes also fire the leaderboard:force-update Redis pub/sub message, so a split frontend + leaderboard deployment still picks up the new scores on the worker’s next tick.