Rest API documentation

We use ctfd internally pretty heavily, and to this point we’ve been hand-jamming instances for every class, which works, but is time consuming. The Rest API is a great add, but the docs are lacking (e.g. /api/v1 API browser doesn’t have the params listed, etc.)

We’ve been internally ‘figuring out’ the various parameters of the Rest APIs internally and would like to assist in documenting this feature with examples (cURL) if the project is interested.

As an example, here is one of the first example scripts we wrote that demonstrates basic functionality:

#!/bin/bash

## Initial setup.  Make admin user and write cookie for follow-on API calls
nonce=$(curl -s http://127.0.0.1:8000/setup -c cookie | grep 'name="nonce"' | awk '{ print $4 }' | cut -d'"' -f2)
curl "http://127.0.0.1:8000/setup" \
-H "Content-Type: application/x-www-form-urlencoded" \
-b cookie \
--data "nonce=$nonce&ctf_name=test&name=admin&email=test"%"40test&password=foobar&user_mode=users"

## Get current user
curl -X GET "http://127.0.0.1:8000/api/v1/users/me" -H  "accept: application/json" -b cookie

## Make a new user
curl -X POST "http://127.0.0.1:8000/api/v1/users" -H "content-type: application/json" -b cookie -d \
'{"name":"foobar",
"email":"[e-mail]",
"password":"123",
"type":"user",
"verified":"false",
"hidden":"false",
"banned":"false"}'

## make a new challenge
curl -X POST "http://127.0.0.1:8000/api/v1/challenges" -H "content-type: application/json" -b cookie -d \
'{"name":"somechal",
"category":"hacks",
"state":"hidden",
"value":"9001",
"type":"standard",
"description":"sample challenge"}'

## add a flag to a challnge
curl -X POST "http://127.0.0.1:8000/api/v1/flags" -H "content-type: application/json" -b cookie -d \
'{"challenge":"1",
"content":"eleventy",
"type":"static"}'

## Upload a file to a challenge.  You need to use a nonce from the admin page of the challenge you're editing.
nonce=$(curl -s http://127.0.0.1:8000/admin/challenges/1 -b cookie | grep nonce | cut -d'"' -f2)
curl -X POST "http://127.0.0.1:8000/api/v1/files" -b cookie  \
-F "file=@some-local-file.png" \
-F "nonce=$nonce" \
-F "challenge=1" \
-F "type=challenge"

Our goal is to fully automate ctfd deployments and allow them to be dynamically generated by sourcing challenge definitions from version control (probably in yaml), and this is the first step in that process.

[ColdHeat]

Swagger UI is now integrated into https://docs.ctfd.io/docs/api/.

[ColdHeat]

I’m closing this since there is now an online interface to view the existing endpoints. Missing areas should be documented by the community over time.

@MillsapCyber https://ctfd.readthedocs.io/en/latest/configuration.html#swagger-ui