REST API

All actions performed via CTFreak’s web UI can also be performed via its RESTful JSON API.

If you are looking for examples of how to use the API, the best way is therefore to open your browser’s network monitor and get examples from the http requests generated by your actions in the web interface.

Some use cases

Execute a task

To execute a given task, start by retrieving its Task Id from its dedicated page in the web UI, then run the following query:

  • HTTP POST: https://{YOUR CTFREAK INSTANCE}/api/v1/executions

  • Body:

    {
  "taskId": "01G9SAGYJM6544WZR8P3W7XB5Q"
}

If you launch a parameterizable task, each parameter is initialized with its default value, but you can override it.

For example, for a task with the parameters:

  • COUNTRY_CODE of type selector
  • CLEAN of type checkbox
  • MAX_RETRY of type integer
  • START_DATE of type date

You can attempt to run the following query:

  • HTTP POST: https://{YOUR CTFREAK INSTANCE}/api/v1/executions

  • Body:

    {
  "taskId": "01G9SAGYJM6544WZR8P3W7XB5Q",
  "parameterMap": {
      "COUNTRY_CODE": "US",
      "CLEAN": true,
      "MAX_RETRY": 5,
      "START_DATE": "2025-01-25"
  }
}

Create a local command task (without shell)

  • HTTP POST: https://{YOUR CTFREAK INSTANCE}/api/v1/tasks

  • Body:

    {
  "projectId": "my-awesome-project",
  "name": "My awesome task",
  "description": "This is really an awesome task",
  "multipleExecutionPolicy": "REJECT",
  "taskNotifierMap": {},
  "scheduledFg": true,
  "cronExpression": "0 9 * * *",
  "timeout": 30,
  "timeoutDurationUnit": "MINUTE",
  "executionRetentionPeriod": 30,
  "taskType": "LOCAL_COMMAND",
  "parameters": [],
  "localCommandTask": {
      "useShellFg": false,
      "commandLine": null,
      "program": "ip",
      "args": [
          "-c",
          "address"
      ],
      "logOutput": "ALWAYS"
  }
}

  • Response:

    {
  "taskId": "01J8ZWXQ1572KC6XGE7T74PT4P",
  "creationTs": 1727647374373505276,
  "updateTs": 1727647374373505276,
  "userId": "01GV1PR26RXBMV4PCPV5TEK1E9",
  "projectId": "my-awesome-project",
  "name": "My awesome task",
  "description": "This is really an awesome task",
  "parameters": [],
  "multipleExecutionPolicy": "REJECT",
  "taskNotifierMap": {},
  "scheduledFg": true,
  "cronExpression": "0 9 * * *",
  "timeout": 30,
  "timeoutDurationUnit": "MINUTE",
  "executionRetentionPeriod": 30,
  "taskType": "LOCAL_COMMAND",
  "localCommandTask": {
      "useShellFg": false,
      "commandLine": null,
      "program": "ip",
      "args": [
          "-c",
          "address"
      ],
      "logOutput": "ALWAYS"
  }
}