Integrations

Client config, analytics, CTFtime, instancer, and admin bot participant routes.

Integration routes help the web app and external services coordinate with rCTF. They cover public runtime config, analytics script delivery, CTFtime handoff, per team challenge instances, and participant admin bot jobs.

The admin bot worker service routes use a separate service token and are documented in Admin.

Version choice#

Client config is available in both V1 and V2. Newer clients usually want V2 because it includes the current analytics, captcha, logo, archive, and instancer fields. The remaining integration routes are version specific.

Timeline behavior#

Instance and participant admin bot routes open after the CTF starts. Admins with challsRead can read through that start gate when they need to review challenges before the event begins.

`GET` Client config

GET /api/[v2,v1]/integrations/client/config

$curl -sS "https://rctf-new-dev.es3n1n.io/api/v2/integrations/client/config"

{
  "kind": "goodClientConfig",
  "message": "The client config was retrieved.",
  "data": {
    "meta": {
      "description": "<description>",
      "imageUrl": "<image-url>"
    },
    "homeContent": "<home-content>",
    "sponsors": [
      {
        "name": "<name>",
        "icon": "<icon>",
        "description": "<description>",
        "url": "<url>"
      }
    ],
    "flagFormatPlaceholder": "<flag-format-placeholder>",
    "analytics": {
      "provider": "<provider>",
      "publicOptions": null
    },
    "ctfName": "<ctf-name>",
    "divisions": null,
    "defaultDivision": "<default-division>",
    "origin": "<origin>",
    "startTime": 0,
    "endTime": 0,
    "userMembers": false,
    "faviconUrl": "<favicon-url>",
    "logoLightUrl": "<logo-light-url>",
    "logoDarkUrl": "<logo-dark-url>",
    "emailEnabled": false,
    "registrationsEnabled": false,
    "ctftime": {
      "clientId": null
    },
    "instancerEnabled": false,
    "isArchived": false,
    "captcha": {
      "provider": "<provider>",
      "publicOptions": null,
      "protectedEndpoints": null
    }
  }
}

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

{
  "kind": "goodClientConfig",
  "message": "The client config was retrieved.",
  "data": {
    "meta": {
      "description": "<description>",
      "imageUrl": "<image-url>"
    },
    "homeContent": "<home-content>",
    "sponsors": [
      {
        "name": "<name>",
        "icon": "<icon>",
        "description": "<description>",
        "url": "<url>"
      }
    ],
    "globalSiteTag": "<global-site-tag>",
    "ctfName": "<ctf-name>",
    "divisions": null,
    "defaultDivision": "<default-division>",
    "origin": "<origin>",
    "startTime": 0,
    "endTime": 0,
    "userMembers": false,
    "faviconUrl": "<favicon-url>",
    "emailEnabled": false,
    "registrationsEnabled": false,
    "ctftime": {
      "clientId": null
    },
    "recaptcha": {
      "siteKey": "<site-key>",
      "protectedActions": [
        "string"
      ]
    }
  }
}

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

This route provides the public runtime settings used by the web app. It includes display settings, event timing, registration state, division names, and public provider settings.

V2 includes the current captcha and analytics fields, logo URLs, archive state, and instancer availability. V1 remains available for older clients and includes the older globalSiteTag and recaptcha fields.

Response fields

meta.descriptionstring

Returned meta description value.

meta.imageUrlstring

Returned meta image url value.

homeContentstring

Returned home content value.

sponsors[].namestring

Display name.

sponsors[].iconstring

Returned sponsors icon value.

sponsors[].descriptionstring

Returned sponsors description value.

sponsors[].urlstring | undefined

Resource URL.

flagFormatPlaceholderstring

Returned flag format placeholder value.

analytics.providerstring

Returned analytics provider value.

analytics.publicOptionsRecord<string, string>

Returned analytics public options value.

ctfNamestring

Returned ctf name value.

divisionsRecord<string, string>

Returned divisions value.

defaultDivisionstring | null | undefined

Returned default division value.

originstring

Returned origin value.

startTimenumber

Returned start time value.

endTimenumber

Returned end time value.

userMembersboolean

Returned user members value.

faviconUrlstring | null

Returned favicon url value.

logoLightUrlstring | null

Returned logo light url value.

logoDarkUrlstring | null

Returned logo dark url value.

emailEnabledboolean

Returned email enabled value.

registrationsEnabledboolean | null

Returned registrations enabled value.

ctftime.clientIdtransform

Returned ctftime client id value.

instancerEnabledboolean

Returned instancer enabled value.

isArchivedboolean

Returned is archived value.

captcha.providerstring

Returned captcha provider value.

captcha.publicOptionsRecord<string, string>

Returned captcha public options value.

Returned captcha protected endpoints value.

Response fields

meta.descriptionstring

Returned meta description value.

meta.imageUrlstring

Returned meta image url value.

homeContentstring

Returned home content value.

sponsors[].namestring

Display name.

sponsors[].iconstring

Returned sponsors icon value.

sponsors[].descriptionstring

Returned sponsors description value.

sponsors[].urlstring | undefined

Resource URL.

globalSiteTagstring | null | undefined

Returned global site tag value.

ctfNamestring

Returned ctf name value.

divisionsRecord<string, string>

Returned divisions value.

defaultDivisionstring | null | undefined

Returned default division value.

originstring

Returned origin value.

startTimenumber

Returned start time value.

endTimenumber

Returned end time value.

userMembersboolean

Returned user members value.

faviconUrlstring | null

Returned favicon url value.

emailEnabledboolean

Returned email enabled value.

registrationsEnabledboolean | null

Returned registrations enabled value.

ctftime.clientIdtransform

Returned ctftime client id value.

recaptcha.siteKeystring

Returned recaptcha site key value.

recaptcha.protectedActionsstring[]

Returned recaptcha protected actions value.

`GET` Analytics script

GET /api/v2/integrations/analytics/script

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

This route proxies the active analytics provider script when analytics are configured. It is intentionally not part of @rctf/types, because it returns JavaScript rather than an rCTF response body.

Response#

The response body is the provider JavaScript. The API keeps the fetched script in memory for one hour.

When analytics are not configured, the route responds with 404. Upstream fetch failures respond with 502.

`GET` Instance status

GET /api/v2/integrations/challs/:id/instance

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

{
  "kind": "goodInstanceStatus",
  "message": "The instance status was retrieved.",
  "data": {
    "status": "stopped",
    "timeLeftMilliseconds": 0,
    "endpoints": [
      {
        "kind": "tcp",
        "host": "<host>",
        "port": 0,
        "title": "<title>"
      }
    ]
  }
}

{
  "kind": "badInstancerError",
  "message": "Instancer has returned an error.",
  "data": {
    "message": "<message>"
  }
}

{
  "kind": "badEndpoint",
  "message": "The request endpoint could not be found."
}

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

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

{
  "kind": "errorInternal",
  "message": "An internal error occurred."
}

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

This route gives the authenticated team’s current instance state for a challenge. It is used to show whether the instance is stopped, starting, running, stopping, or in an error state.

When no instancer provider is configured, or when the challenge has no instancer settings, the route returns 404 badEndpoint. Provider errors return 400 badInstancerError with a provider message.

Path parameters

id
*
 required

string

Unique identifier.

Response fields

status"stopped" | "running" | "starting" | "stopping" | "errored"

Returned status value.

timeLeftMillisecondsnumber | null

Returned time left milliseconds value.

endpoints[].kind"tcp" | "tcp-ssl" | "http" | "https"

Response or object kind.

endpoints[].hoststring

Returned endpoints host value.

endpoints[].portnumber

Returned endpoints port value.

endpoints[].titlestring | undefined

Returned endpoints title value.

endpoints are returned in the order configured for the challenge. Endpoint kinds include tcp, tcp-ssl, http, and https.

`PUT` Start an instance

PUT /api/v2/integrations/challs/:id/instance

$curl -sS "https://rctf-new-dev.es3n1n.io/api/v2/integrations/challs/challenge-id/instance" \
  -X PUT \
  -H "Authorization: Bearer <auth-token>" \
  --json '{
    "captchaCode": "optional-captcha-code"
  }'

{
  "kind": "goodInstanceStatus",
  "message": "The instance status was retrieved.",
  "data": {
    "status": "stopped",
    "timeLeftMilliseconds": 0,
    "endpoints": [
      {
        "kind": "tcp",
        "host": "<host>",
        "port": 0,
        "title": "<title>"
      }
    ]
  }
}

{
  "kind": "badInstancerError",
  "message": "Instancer has returned an error.",
  "data": {
    "message": "<message>"
  }
}

{
  "kind": "badEndpoint",
  "message": "The request endpoint could not be found."
}

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

{
  "kind": "badCaptcha",
  "message": "The captcha verification failed."
}

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

{
  "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 (bypass challsRead)
Permissions: No extra permissions
Captcha: instancerStart
Rate limit: No rate limit

This route asks the instancer provider to start an instance for the authenticated team. If the provider needs time to finish provisioning, the response can report starting before a later status request reports running.

Captcha is checked only when the deployment protects instancerStart.

Path parameters

id
*
 required

string

Unique identifier.

Request body

captchaCodestring

Captcha challenge token.

Response fields

status"stopped" | "running" | "starting" | "stopping" | "errored"

Returned status value.

timeLeftMillisecondsnumber | null

Returned time left milliseconds value.

endpoints[].kind"tcp" | "tcp-ssl" | "http" | "https"

Response or object kind.

endpoints[].hoststring

Returned endpoints host value.

endpoints[].portnumber

Returned endpoints port value.

endpoints[].titlestring | undefined

Returned endpoints title value.

`PATCH` Extend an instance

PATCH /api/v2/integrations/challs/:id/instance

$curl -sS "https://rctf-new-dev.es3n1n.io/api/v2/integrations/challs/challenge-id/instance" \
  -X PATCH \
  -H "Authorization: Bearer <auth-token>" \
  --json '{
    "captchaCode": "optional-captcha-code"
  }'

{
  "kind": "goodInstanceStatus",
  "message": "The instance status was retrieved.",
  "data": {
    "status": "stopped",
    "timeLeftMilliseconds": 0,
    "endpoints": [
      {
        "kind": "tcp",
        "host": "<host>",
        "port": 0,
        "title": "<title>"
      }
    ]
  }
}

{
  "kind": "badInstancerError",
  "message": "Instancer has returned an error.",
  "data": {
    "message": "<message>"
  }
}

{
  "kind": "badEndpoint",
  "message": "The request endpoint could not be found."
}

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

{
  "kind": "badCaptcha",
  "message": "The captcha verification failed."
}

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

{
  "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 (bypass challsRead)
Permissions: No extra permissions
Captcha: instancerExtend
Rate limit: No rate limit

This route asks the instancer provider to extend the authenticated team’s running instance. The returned status includes the updated remaining time when the provider reports one.

Captcha is checked only when the deployment protects instancerExtend.

Path parameters

id
*
 required

string

Unique identifier.

Request body

captchaCodestring

Captcha challenge token.

Response fields

status"stopped" | "running" | "starting" | "stopping" | "errored"

Returned status value.

timeLeftMillisecondsnumber | null

Returned time left milliseconds value.

endpoints[].kind"tcp" | "tcp-ssl" | "http" | "https"

Response or object kind.

endpoints[].hoststring

Returned endpoints host value.

endpoints[].portnumber

Returned endpoints port value.

endpoints[].titlestring | undefined

Returned endpoints title value.

`DELETE` Stop an instance

DELETE /api/v2/integrations/challs/:id/instance

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

{
  "kind": "goodInstanceStatus",
  "message": "The instance status was retrieved.",
  "data": {
    "status": "stopped",
    "timeLeftMilliseconds": 0,
    "endpoints": [
      {
        "kind": "tcp",
        "host": "<host>",
        "port": 0,
        "title": "<title>"
      }
    ]
  }
}

{
  "kind": "badInstancerError",
  "message": "Instancer has returned an error.",
  "data": {
    "message": "<message>"
  }
}

{
  "kind": "badEndpoint",
  "message": "The request endpoint could not be found."
}

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

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

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

This route asks the instancer provider to stop the authenticated team’s instance. The response reports the latest state returned by the provider.

Path parameters

id
*
 required

string

Unique identifier.

Response fields

status"stopped" | "running" | "starting" | "stopping" | "errored"

Returned status value.

timeLeftMillisecondsnumber | null

Returned time left milliseconds value.

endpoints[].kind"tcp" | "tcp-ssl" | "http" | "https"

Response or object kind.

endpoints[].hoststring

Returned endpoints host value.

endpoints[].portnumber

Returned endpoints port value.

endpoints[].titlestring | undefined

Returned endpoints title value.

`GET` Admin bot config

GET /api/v2/integrations/challs/:id/admin-bot/config

$curl -sS "https://rctf-new-dev.es3n1n.io/api/v2/integrations/challs/challenge-id/admin-bot/config"

{
  "kind": "goodAdminBotConfig",
  "message": "The admin bot config was retrieved successfully.",
  "data": {
    "sourceCode": "<source-code>",
    "fileExtension": "<file-extension>"
  }
}

{
  "kind": "badEndpoint",
  "message": "The request endpoint could not be found."
}

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

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

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

This route gives participants the released admin bot challenge source and the file extension for that source. Challenge authors can use this to show the exact code participants will write against.

Path parameters

id
*
 required

string

Unique identifier.

Response fields

sourceCodestring

Returned source code value.

fileExtensionstring

Returned file extension value.

`POST` Submit admin bot job

POST /api/v2/integrations/challs/:id/admin-bot

$curl -sS "https://rctf-new-dev.es3n1n.io/api/v2/integrations/challs/challenge-id/admin-bot" \
  -H "Authorization: Bearer <auth-token>" \
  --json '{
    "inputs": {
      "url": "https://challenge.example.com/"
    },
    "captchaCode": "optional-captcha-code"
  }'

{
  "kind": "goodAdminBotJobSubmitted",
  "message": "The admin bot job was submitted successfully.",
  "data": {
    "jobId": "<job-id>"
  }
}

{
  "kind": "badAdminBotConfig",
  "message": "Invalid admin bot configuration.",
  "data": {
    "error": "<error>"
  }
}

{
  "kind": "badCaptcha",
  "message": "The captcha verification failed."
}

{
  "kind": "badInstancerState",
  "message": "Instancer precondition not met.",
  "data": {
    "error": "<error>"
  }
}

{
  "kind": "badEndpoint",
  "message": "The request endpoint could not be found."
}

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

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

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

{
  "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 (bypass challsRead)
Permissions: No extra permissions
Captcha: adminBotSubmit
Rate limit: Burst 1, refill window 10000 ms per user and challenge.

This route submits an admin bot job for the authenticated team. Participants send values for the input names configured on the challenge.

Only one queued or running job is allowed per user and challenge. When the challenge depends on a running instance, the route returns 400 badInstancerState if the instance is missing, stopped, or expires before the admin bot timeout.

Path parameters

id
*
 required

string

Unique identifier.

Request body

inputs
*
 required

record

Request body field for inputs.

captchaCodestring

Captcha challenge token.

Response fields

jobIdstring

Job identifier.

`GET` Admin bot job status

GET /api/v2/integrations/challs/:id/admin-bot/status

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

{
  "kind": "goodAdminBotJobStatus",
  "message": "The admin bot job status was retrieved successfully.",
  "data": {
    "job": {
      "id": "<id>",
      "status": "queued",
      "createdAt": "<created-at>",
      "queuePosition": 0,
      "logs": "<logs>"
    }
  }
}

{
  "kind": "badEndpoint",
  "message": "The request endpoint could not be found."
}

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

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

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

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

This route gives the authenticated team’s active admin bot job for a challenge. The job field is null when there is no queued or running job.

Path parameters

id
*
 required

string

Unique identifier.

Response fields

job.idstring

Unique identifier.

job.status"queued" | "running" | "completed" | "failed"

Returned job status value.

job.createdAtstring

Creation timestamp.

job.queuePositionnumber | null

Returned job queue position value.

job.logsstring | null

Returned job logs value.

`GET` Admin bot job history

GET /api/v2/integrations/challs/:id/admin-bot/history

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

{
  "kind": "goodAdminBotJobHistory",
  "message": "The admin bot job history was retrieved successfully.",
  "data": {
    "jobs": [
      {
        "id": "<id>",
        "status": "queued",
        "createdAt": "<created-at>",
        "hasLogs": false
      }
    ]
  }
}

{
  "kind": "badEndpoint",
  "message": "The request endpoint could not be found."
}

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

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

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

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

This route gives the retained completed and failed admin bot jobs for the authenticated team on a challenge. It is useful for showing recent submissions without including the full log body in the list.

Path parameters

id
*
 required

string

Unique identifier.

Response fields

jobs[].idstring

Unique identifier.

jobs[].status"queued" | "running" | "completed" | "failed"

Returned jobs status value.

jobs[].createdAtstring

Creation timestamp.

jobs[].hasLogsboolean

Returned jobs has logs value.

`GET` Admin bot job logs

GET /api/v2/integrations/challs/:id/admin-bot/jobs/:jobId/logs

$curl -sS "https://rctf-new-dev.es3n1n.io/api/v2/integrations/challs/challenge-id/admin-bot/jobs/job-id/logs" \
  -H "Authorization: Bearer <auth-token>"

{
  "kind": "goodAdminBotJobLogs",
  "message": "The admin bot job logs were retrieved successfully.",
  "data": {
    "logs": "<logs>"
  }
}

{
  "kind": "badEndpoint",
  "message": "The request endpoint could not be found."
}

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

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

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

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

This route gives the retained logs for a completed or failed admin bot job. The logs field is null when logs are not available.

Path parameters

id
*
 required

string

Unique identifier.

jobId
*
 required

string

Job identifier.

Response fields

logsstring | null

Returned logs value.

`POST` CTFtime callback

POST /api/v1/integrations/ctftime/callback

$curl -sS "https://rctf-new-dev.es3n1n.io/api/v1/integrations/ctftime/callback" \
  --json '{
    "ctftimeCode": "oauth-code"
  }'

{
  "kind": "goodCtftimeToken",
  "message": "The CTFtime token was created.",
  "data": {
    "ctftimeToken": "<ctftime-token>",
    "ctftimeName": "<ctftime-name>",
    "ctftimeId": null
  }
}

{
  "kind": "badEndpoint",
  "message": "The request endpoint could not be found."
}

{
  "kind": "badCtftimeCode",
  "message": "The CTFtime code 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: Public
Gate: None
Permissions: No extra permissions
Captcha: No captcha
Rate limit: No rate limit

This V1 route exchanges a CTFtime OAuth code for a short lived CTFtime auth token. That token can then be used with registration, verification, login, or account linking flows.

Request body

ctftimeCode
*
 required

string

Request body field for ctftime code.

Response fields

ctftimeTokenstring

CTFtime authentication token.

ctftimeNamestring

Returned ctftime name value.

ctftimeIdtransform

Returned ctftime id value.

`GET` CTFtime leaderboard

GET /api/v1/integrations/ctftime/leaderboard

Auth: Required
Gate: None
Permissions: leaderboardRead
Captcha: No captcha
Rate limit: No rate limit

This V1 route provides the leaderboard export expected by CTFtime. It is the rare typed route that returns the body directly instead of using the rCTF response wrapper.

Response#

The response body is the raw CTFtime leaderboard.

{
  "standings": [
    {
      "pos": 1,
      "team": "otter-sec",
      "score": 1200
    }
  ]
}

Field	Type	Notes
`standings`	`{ pos: number, team: string, score: number }[]`	Ordered standings rows.