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.

Authentication

OAuth Token

By default, API calls require an OAuth token obtained from the token endpoint.

Personal Access Tokens

You can generate personal access tokens to authenticate API calls without using the OAuth token endpoint.

This is particularly useful for integrating CTFreak with third-party tools such as Zabbix, monitoring systems, or CI/CD pipelines.

To create a personal access token, go to your Profile → Personal Access Tokens → New token and provide:

  • Name: A descriptive name for the token (e.g., “Zabbix monitoring”)
  • Expiration date (optional): If left blank, the token will never expire

After creation, the token value (prefixed with ctpat_) will be displayed only once. Make sure to save it immediately.

To use a personal access token, include it in the Authorization header of your API requests:

Authorization: Bearer ctpat_eZf9pKuAE-F6Oo7i5QXiWYn6UMHNTzEA6rcS0GI1ysw=

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": "2026-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"
  }
}