Integrations

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

Last updated Jul 15, 2026

Route	Endpoint
Client config	`GET /api/[v2,v1]/integrations/client/config`
Analytics script	`GET /api/v2/integrations/analytics/script`
Instance status	`GET /api/v2/integrations/challs/:id/instance`
Start an instance	`PUT /api/v2/integrations/challs/:id/instance`
Extend an instance	`PATCH /api/v2/integrations/challs/:id/instance`
Stop an instance	`DELETE /api/v2/integrations/challs/:id/instance`
Admin bot config	`GET /api/v2/integrations/challs/:id/admin-bot/config`
Submit admin bot job	`POST /api/v2/integrations/challs/:id/admin-bot`
Admin bot job status	`GET /api/v2/integrations/challs/:id/admin-bot/status`
Admin bot job history	`GET /api/v2/integrations/challs/:id/admin-bot/history`
Admin bot job logs	`GET /api/v2/integrations/challs/:id/admin-bot/jobs/:jobId/logs`
CTFtime callback	`POST /api/v1/integrations/ctftime/callback`
CTFtime leaderboard	`GET /api/v1/integrations/ctftime/leaderboard`

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

Edit this page View Markdown

Last updated Jul 15, 2026

curl -sS "https://rctf.osec.io/api/v2/integrations/client/config"

1
{
2
  "kind": "goodClientConfigV2",
3
  "message": "The client config was retrieved.",
4
  "data": {
5
    "meta": {
6
      "description": "A jeopardy-style CTF.",
7
      "imageUrl": "https://rctf.osec.io/preview.png"
8
    },
9
    "homeContent": "# Welcome",
10
    "sponsors": [
11
      {
12
        "name": "osec",
13
        "icon": "https://rctf.osec.io/sponsors/osec-light.png",
14
        "iconLight": "https://rctf.osec.io/sponsors/osec-light.png",
15
        "iconDark": "https://rctf.osec.io/sponsors/osec-dark.png",
16
        "description": "Security research.",
17
        "url": "https://osec.io"
18
      }
19
    ],
20
    "flagFormatPlaceholder": "rctf{...}",
21
    "analytics": {
22
      "provider": "plausible",
23
      "publicOptions": {
24
        "domain": "rctf.osec.io"
25
      }
26
    },
27
    "ctfName": "rCTF",
28
    "divisions": {
29
      "open": "Open"
30
    },
31
    "defaultDivision": "open",
32
    "origin": "https://rctf.osec.io",
33
    "startTime": 1710000000000,
34
    "endTime": 1710864000000,
35
    "userMembers": true,
36
    "faviconUrl": "https://rctf.osec.io/favicon.ico",
37
    "logoLightUrl": "https://rctf.osec.io/logo-light.png",
38
    "logoDarkUrl": "https://rctf.osec.io/logo-dark.png",
39
    "emailEnabled": true,
40
    "registrationsEnabled": true,
41
    "ctftime": {
42
      "clientId": "123456"
43
    },
44
    "instancerEnabled": true,
45
    "isArchived": false,
46
    "captcha": {
47
      "provider": "hcaptcha",
48
      "publicOptions": {
49
        "siteKey": "<captcha-site-key>"
50
      },
51
      "protectedEndpoints": {
52
        "register": true,
53
        "recover": true,
54
        "setEmail": false,
55
        "instancerStart": false,
56
        "instancerExtend": false,
57
        "avatarUpload": false,
58
        "adminBotSubmit": false
59
      }
60
    }
61
  }
62
}

curl -sS "https://rctf.osec.io/api/v1/integrations/client/config"

1
{
2
  "kind": "goodClientConfig",
3
  "message": "The client config was retrieved.",
4
  "data": {
5
    "meta": {
6
      "description": "A jeopardy-style CTF.",
7
      "imageUrl": "https://rctf.osec.io/preview.png"
8
    },
9
    "homeContent": "# Welcome",
10
    "sponsors": [
11
      {
12
        "name": "osec",
13
        "icon": "https://rctf.osec.io/sponsors/osec.png",
14
        "description": "Security research.",
15
        "url": "https://osec.io"
16
      }
17
    ],
18
    "globalSiteTag": "<global-site-tag>",
19
    "ctfName": "rCTF",
20
    "divisions": {
21
      "open": "Open"
22
    },
23
    "defaultDivision": "<default-division>",
24
    "origin": "https://rctf.osec.io",
25
    "startTime": 1710000000000,
26
    "endTime": 1710864000000,
27
    "userMembers": true,
28
    "faviconUrl": "<favicon-url>",
29
    "emailEnabled": true,
30
    "registrationsEnabled": false,
31
    "ctftime": {
32
      "clientId": "123456"
33
    },
34
    "recaptcha": {
35
      "siteKey": "<recaptcha-site-key>",
36
      "protectedActions": [
37
        "register"
38
      ]
39
    }
40
  }
41
}

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: Meta description used for link previews.
meta.imageUrlstring: Preview image URL.
homeContentstring: Markdown content shown on the home page.
sponsors[].namestring: Sponsor name.
sponsors[].iconstring | undefined: Deprecated. Mirrors iconLight (or iconDark when only it is set) for old clients.
sponsors[].iconLightstring | undefined: Sponsor icon URL for light mode; may be absent on data from older versions.
sponsors[].iconDarkstring | undefined: Sponsor icon URL for dark mode; may be absent on data from older versions.
sponsors[].descriptionstring: Sponsor description.
sponsors[].urlstring | undefined: Sponsor link, when present.
flagFormatPlaceholderstring: Placeholder shown in the flag submission box.
analytics.providerstring: Analytics provider name.
analytics.publicOptionsRecord<string, string>: Public, client-safe analytics options.
ctfNamestring: Name of the CTF.
divisionsRecord<string, string>: Division keys mapped to display names.
defaultDivisionstring | null | undefined: Division selected by default, or null when unset.
originstring: Canonical origin of the deployment.
startTimenumber: CTF start time as a Unix timestamp in milliseconds.
endTimenumber: CTF end time as a Unix timestamp in milliseconds.
userMembersboolean: Whether teams may add individual members.
faviconUrlstring | null: Favicon URL, or null when unset.
logoLightUrlstring | null: Light-theme logo URL, or null when unset.
logoDarkUrlstring | null: Dark-theme logo URL, or null when unset.
emailEnabledboolean: Whether email-based auth is enabled.
registrationsEnabledboolean | null: Whether registrations are open, or null when unset.
ctftime.clientIdstring: CTFtime OAuth client ID.
instancerEnabledboolean: Whether the challenge instancer is enabled.
isArchivedboolean: Whether the CTF is archived (read-only).
captcha.providerstring: Captcha provider name.
captcha.publicOptionsRecord<string, string>: Public, client-safe captcha options.
captcha.protectedEndpointsRecord<"register" | "recover" | "setEmail" | "instancerStart" | "instancerExtend" | "avatarUpload" | "adminBotSubmit", boolean>: Which actions require a captcha.

Response fields

meta.descriptionstring: Meta description used for link previews.
meta.imageUrlstring: Preview image URL.
homeContentstring: Markdown content shown on the home page.
sponsors[].namestring: Sponsor name.
sponsors[].iconstring: Sponsor icon URL.
sponsors[].descriptionstring: Sponsor description.
sponsors[].urlstring | undefined: Sponsor link, when present.
globalSiteTagstring: Analytics global site tag, or null when unset.
ctfNamestring: Name of the CTF.
divisionsRecord<string, string>: Division keys mapped to display names.
defaultDivisionstring: Division selected by default, or null when unset.
originstring: Canonical origin of the deployment.
startTimenumber: CTF start time as a Unix timestamp in milliseconds.
endTimenumber: CTF end time as a Unix timestamp in milliseconds.
userMembersboolean: Whether teams may add individual members.
faviconUrlstring: Favicon URL, or null when unset.
emailEnabledboolean: Whether email-based auth is enabled.
registrationsEnabledboolean: Whether registrations are open, or null when unset.
ctftimeobject: CTFtime integration config, or null when disabled.
recaptchaobject: reCAPTCHA config, or null when disabled.

`GET` Analytics script

GET /api/v2/integrations/analytics/script

Edit this page View Markdown

Last updated Jul 15, 2026

curl -sS "https://demo.rctf.osec.io/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

Edit this page View Markdown

Last updated Jul 15, 2026

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

1
{
2
  "kind": "goodInstanceStatus",
3
  "message": "The instance status was retrieved.",
4
  "data": {
5
    "status": "running",
6
    "timeLeftMilliseconds": 600000,
7
    "endpoints": [
8
      {
9
        "kind": "tcp",
10
        "host": "baby-rev.rctf.osec.io",
11
        "port": 1337,
12
        "title": "nc",
13
        "text": "nc baby-rev.rctf.osec.io 1337"
14
      }
15
    ]
16
  }
17
}

1
{
2
  "kind": "badInstancerError",
3
  "message": "Instancer has returned an error.",
4
  "data": {
5
    "message": "Instancer request timed out."
6
  }
7
}

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

1
{
2
  "kind": "badChallenge",
3
  "message": "The challenge could not be found."
4
}

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

1
{
2
  "kind": "errorInternal",
3
  "message": "An internal error occurred."
4
}

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*string: Challenge ID.

Response fields

status"stopped" | "running" | "starting" | "stopping" | "errored": Current lifecycle state of the instance.
timeLeftMillisecondsnumber | null: Milliseconds until expiry, or null when not running.
endpoints[].kind"tcp" | "tcp-ssl" | "http" | "https" | "raw": Exposure protocol.
endpoints[].hoststring: Reachable host name.
endpoints[].portnumber: Reachable port.
endpoints[].titlestring | undefined: Short label for the endpoint, when present.
endpoints[].textstring | undefined: Connection hint shown to players, when present.

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

Edit this page View Markdown

Last updated Jul 15, 2026

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

1
{
2
  "kind": "goodInstanceStatus",
3
  "message": "The instance status was retrieved.",
4
  "data": {
5
    "status": "running",
6
    "timeLeftMilliseconds": 600000,
7
    "endpoints": [
8
      {
9
        "kind": "tcp",
10
        "host": "baby-rev.rctf.osec.io",
11
        "port": 1337,
12
        "title": "nc",
13
        "text": "nc baby-rev.rctf.osec.io 1337"
14
      }
15
    ]
16
  }
17
}

1
{
2
  "kind": "badInstancerError",
3
  "message": "Instancer has returned an error.",
4
  "data": {
5
    "message": "Instancer request timed out."
6
  }
7
}

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

1
{
2
  "kind": "badChallenge",
3
  "message": "The challenge could not be found."
4
}

1
{
2
  "kind": "badCaptcha",
3
  "message": "The captcha verification failed."
4
}

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

1
{
2
  "kind": "badJson",
3
  "message": "The request JSON body is malformed."
4
}

1
{
2
  "kind": "badBody",
3
  "message": "The request body does not meet requirements.",
4
  "data": {
5
    "reason": "name: Required"
6
  }
7
}

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*string: Challenge ID.

Request body

captchaCodestring: Checked only when captcha protects this route.

Response fields

status"stopped" | "running" | "starting" | "stopping" | "errored": Current lifecycle state of the instance.
timeLeftMillisecondsnumber | null: Milliseconds until expiry, or null when not running.
endpoints[].kind"tcp" | "tcp-ssl" | "http" | "https" | "raw": Exposure protocol.
endpoints[].hoststring: Reachable host name.
endpoints[].portnumber: Reachable port.
endpoints[].titlestring | undefined: Short label for the endpoint, when present.
endpoints[].textstring | undefined: Connection hint shown to players, when present.

`PATCH` Extend an instance

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

Edit this page View Markdown

Last updated Jul 15, 2026

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

1
{
2
  "kind": "goodInstanceStatus",
3
  "message": "The instance status was retrieved.",
4
  "data": {
5
    "status": "running",
6
    "timeLeftMilliseconds": 600000,
7
    "endpoints": [
8
      {
9
        "kind": "tcp",
10
        "host": "baby-rev.rctf.osec.io",
11
        "port": 1337,
12
        "title": "nc",
13
        "text": "nc baby-rev.rctf.osec.io 1337"
14
      }
15
    ]
16
  }
17
}

1
{
2
  "kind": "badInstancerError",
3
  "message": "Instancer has returned an error.",
4
  "data": {
5
    "message": "Instancer request timed out."
6
  }
7
}

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

1
{
2
  "kind": "badChallenge",
3
  "message": "The challenge could not be found."
4
}

1
{
2
  "kind": "badCaptcha",
3
  "message": "The captcha verification failed."
4
}

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

1
{
2
  "kind": "badJson",
3
  "message": "The request JSON body is malformed."
4
}

1
{
2
  "kind": "badBody",
3
  "message": "The request body does not meet requirements.",
4
  "data": {
5
    "reason": "name: Required"
6
  }
7
}

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*string: Challenge ID.

Request body

captchaCodestring: Checked only when captcha protects this route.

Response fields

status"stopped" | "running" | "starting" | "stopping" | "errored": Current lifecycle state of the instance.
timeLeftMillisecondsnumber | null: Milliseconds until expiry, or null when not running.
endpoints[].kind"tcp" | "tcp-ssl" | "http" | "https" | "raw": Exposure protocol.
endpoints[].hoststring: Reachable host name.
endpoints[].portnumber: Reachable port.
endpoints[].titlestring | undefined: Short label for the endpoint, when present.
endpoints[].textstring | undefined: Connection hint shown to players, when present.

`DELETE` Stop an instance

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

Edit this page View Markdown

Last updated Jul 15, 2026

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

1
{
2
  "kind": "goodInstanceStatus",
3
  "message": "The instance status was retrieved.",
4
  "data": {
5
    "status": "running",
6
    "timeLeftMilliseconds": 600000,
7
    "endpoints": [
8
      {
9
        "kind": "tcp",
10
        "host": "baby-rev.rctf.osec.io",
11
        "port": 1337,
12
        "title": "nc",
13
        "text": "nc baby-rev.rctf.osec.io 1337"
14
      }
15
    ]
16
  }
17
}

1
{
2
  "kind": "badInstancerError",
3
  "message": "Instancer has returned an error.",
4
  "data": {
5
    "message": "Instancer request timed out."
6
  }
7
}

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

1
{
2
  "kind": "badChallenge",
3
  "message": "The challenge could not be found."
4
}

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

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*string: Challenge ID.

Response fields

status"stopped" | "running" | "starting" | "stopping" | "errored": Current lifecycle state of the instance.
timeLeftMillisecondsnumber | null: Milliseconds until expiry, or null when not running.
endpoints[].kind"tcp" | "tcp-ssl" | "http" | "https" | "raw": Exposure protocol.
endpoints[].hoststring: Reachable host name.
endpoints[].portnumber: Reachable port.
endpoints[].titlestring | undefined: Short label for the endpoint, when present.
endpoints[].textstring | undefined: Connection hint shown to players, when present.

`GET` Admin bot config

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

Edit this page View Markdown

Last updated Jul 15, 2026

curl -sS "https://rctf.osec.io/api/v2/integrations/challs/challenge-id/admin-bot/config"

1
{
2
  "kind": "goodAdminBotConfig",
3
  "message": "The admin bot config was retrieved successfully.",
4
  "data": {
5
    "sourceCode": "await page.goto(url)",
6
    "fileExtension": "js"
7
  }
8
}

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

1
{
2
  "kind": "badChallenge",
3
  "message": "The challenge could not be found."
4
}

1
{
2
  "kind": "badToken",
3
  "message": "The token provided is invalid."
4
}

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*string: Challenge ID.

Response fields

sourceCodestring: Admin-bot script source code.
fileExtensionstring: File extension for the script language.

`POST` Submit admin bot job

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

Edit this page View Markdown

Last updated Jul 15, 2026

curl -sS "https://rctf.osec.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"
  }'

1
{
2
  "kind": "goodAdminBotJobSubmitted",
3
  "message": "The admin bot job was submitted successfully.",
4
  "data": {
5
    "jobId": "job-1a2b3c"
6
  }
7
}

1
{
2
  "kind": "badAdminBotConfig",
3
  "message": "Invalid admin bot configuration.",
4
  "data": {
5
    "error": "Unknown admin-bot config code."
6
  }
7
}

1
{
2
  "kind": "badCaptcha",
3
  "message": "The captcha verification failed."
4
}

1
{
2
  "kind": "badInstancerState",
3
  "message": "Instancer precondition not met.",
4
  "data": {
5
    "error": "Instance already running."
6
  }
7
}

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

1
{
2
  "kind": "badChallenge",
3
  "message": "The challenge could not be found."
4
}

1
{
2
  "kind": "badRateLimit",
3
  "message": "You are trying this too fast.",
4
  "data": {
5
    "timeLeft": 600000
6
  }
7
}

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

1
{
2
  "kind": "badToken",
3
  "message": "The token provided is invalid."
4
}

1
{
2
  "kind": "badJson",
3
  "message": "The request JSON body is malformed."
4
}

1
{
2
  "kind": "badBody",
3
  "message": "The request body does not meet requirements.",
4
  "data": {
5
    "reason": "name: Required"
6
  }
7
}

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*string: Challenge ID.

Request body

inputs*record: Admin-bot input values keyed by the config field name.
captchaCodestring: Checked only when captcha protects this route.

Response fields

jobIdstring: ID of the newly submitted job.

`GET` Admin bot job status

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

Edit this page View Markdown

Last updated Jul 15, 2026

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

1
{
2
  "kind": "goodAdminBotJobStatus",
3
  "message": "The admin bot job status was retrieved successfully.",
4
  "data": {
5
    "job": {
6
      "id": "job-1a2b3c",
7
      "status": "running",
8
      "createdAt": "2024-03-09T00:00:00.000Z",
9
      "queuePosition": 3,
10
      "logs": "Visiting target..."
11
    }
12
  }
13
}

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

1
{
2
  "kind": "badChallenge",
3
  "message": "The challenge could not be found."
4
}

1
{
2
  "kind": "badToken",
3
  "message": "The token provided is invalid."
4
}

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

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*string: Challenge ID.

Response fields

job.idstring: Admin-bot job ID.
job.status"queued" | "running" | "completed" | "failed": Current job status.
job.createdAtstring: Job creation time as an ISO 8601 string.
job.queuePositionnumber | null: Position in the queue, or null when not queued.
job.logsstring | null: Captured job logs, or null when none.

`GET` Admin bot job history

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

Edit this page View Markdown

Last updated Jul 15, 2026

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

1
{
2
  "kind": "goodAdminBotJobHistory",
3
  "message": "The admin bot job history was retrieved successfully.",
4
  "data": {
5
    "jobs": [
6
      {
7
        "id": "job-1a2b3c",
8
        "status": "completed",
9
        "createdAt": "2024-03-09T00:00:00.000Z",
10
        "hasLogs": true
11
      }
12
    ]
13
  }
14
}

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

1
{
2
  "kind": "badChallenge",
3
  "message": "The challenge could not be found."
4
}

1
{
2
  "kind": "badToken",
3
  "message": "The token provided is invalid."
4
}

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

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*string: Challenge ID.

Response fields

jobs[].idstring: Admin-bot job ID.
jobs[].status"queued" | "running" | "completed" | "failed": Current job status.
jobs[].createdAtstring: Job creation time as an ISO 8601 string.
jobs[].hasLogsboolean: Whether logs are available for the job.

`GET` Admin bot job logs

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

Edit this page View Markdown

Last updated Jul 15, 2026

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

1
{
2
  "kind": "goodAdminBotJobLogs",
3
  "message": "The admin bot job logs were retrieved successfully.",
4
  "data": {
5
    "logs": "Visiting target..."
6
  }
7
}

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

1
{
2
  "kind": "badChallenge",
3
  "message": "The challenge could not be found."
4
}

1
{
2
  "kind": "badToken",
3
  "message": "The token provided is invalid."
4
}

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

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*string: Challenge ID.
jobId*string: Admin-bot job ID.

Response fields

logsstring | null: Captured job logs, or null when none.

`POST` CTFtime callback

POST /api/v1/integrations/ctftime/callback

Edit this page View Markdown

Last updated Jul 15, 2026

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

1
{
2
  "kind": "goodCtftimeToken",
3
  "message": "The CTFtime token was created.",
4
  "data": {
5
    "ctftimeToken": "<ctftime-token>",
6
    "ctftimeName": "otter-sec",
7
    "ctftimeId": "123456"
8
  }
9
}

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

1
{
2
  "kind": "badCtftimeCode",
3
  "message": "The CTFtime code is invalid."
4
}

1
{
2
  "kind": "badJson",
3
  "message": "The request JSON body is malformed."
4
}

1
{
2
  "kind": "badBody",
3
  "message": "The request body does not meet requirements.",
4
  "data": {
5
    "reason": "name: Required"
6
  }
7
}

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*string: CTFtime OAuth authorization code.

Response fields

ctftimeTokenstring: Opaque token linking the rCTF account to CTFtime.
ctftimeNamestring: CTFtime team name.
ctftimeIdstring: CTFtime team ID.

`GET` CTFtime leaderboard

GET /api/v1/integrations/ctftime/leaderboard

Edit this page View Markdown

Last updated Jul 15, 2026

curl -sS "https://demo.rctf.osec.io/api/v1/integrations/ctftime/leaderboard" \
  -H "Authorization: Bearer <auth-token>"

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.

1
{
2
  "standings": [
3
    {
4
      "pos": 1,
5
      "team": "otter-sec",
6
      "score": 1200
7
    }
8
  ]
9
}

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