16.1.1.23. Periodic Task endpoints

The periodic-tasks REST API manages scheduled jobs that privacyIDEA runs on its own nodes (cleanup tasks, statistics aggregation, expiring tokens, …). See Periodic Tasks for the conceptual chapter.

All endpoints require admin authentication. Read access for the task list, individual task definitions and the lookup endpoints (available task modules, configured nodes, per-module option schemas) is gated by the admin policy action periodictask_read; create, update, enable, disable and delete are gated by periodictask_write.

GET /periodictask/taskmodules/

Return the list of task module identifiers known to this server.

Requires admin authentication and the policy action periodictask_read.

Status Codes:

  • 200 OK – list of task module names in result.value.

GET /periodictask/nodes/

Return the list of privacyIDEA node names declared in the server configuration. Periodic tasks are scheduled per node — only nodes listed here can be assigned to a task.

Requires admin authentication and the policy action periodictask_read.

Status Codes:

  • 200 OK – list of node names in result.value.

GET /periodictask/options/(taskmodule)

Return the option schema for a given task module: a dictionary mapping each option key to a description dictionary that the WebUI uses to render the per-task configuration form.

Requires admin authentication and the policy action periodictask_read.

Parameters:

  • taskmodule – path component, the task module identifier.

Status Codes:

  • 200 OK – dict of option descriptors in result.value.

GET /periodictask/

Return all periodic task definitions. Each entry includes its schedule, the nodes it runs on, the task module, the per-module options, and last_update / last_runs timestamps formatted as %Y-%m-%d %H:%M:%S.%f%z.

Requires admin authentication and the policy action periodictask_read.

Status Codes:

  • 200 OK – list of periodic task dictionaries in result.value.

GET /periodictask/(ptaskid)

Return the dictionary describing a single periodic task.

Requires admin authentication and the policy action periodictask_read.

Parameters:

  • ptaskid – path component, the numeric id of the periodic task.

Status Codes:

  • 200 OK – periodic task dictionary in result.value.

  • 404 Not Found – no periodic task with that id exists.

POST /periodictask/

Create or update a periodic task definition. Pass an existing id to update; omit it to create a new task.

Requires admin authentication and the policy action periodictask_write.

JSON Parameters:

  • id – id of an existing task to update; omit to create.

  • name – human-readable name of the task (required).

  • active – True (default) to enable the task, False to create it disabled.

  • retry_if_failed – True (default) to retry the task if a run fails.

  • interval – cron-style schedule string (required).

  • nodes – comma-separated list of node names the task runs on (required, must be non-empty).

  • taskmodule – task module identifier (required); must be listed in GET /periodictask/taskmodules/.

  • ordering – integer >= 0; tasks with lower ordering run first.

  • options – dictionary of task-module-specific options (or a JSON-encoded string of one).

Status Codes:

  • 200 OK – id of the task in result.value.

  • 400 Bad Request – nodes is empty, taskmodule is unknown, or options is not a dictionary.

POST /periodictask/enable/(ptaskid)

Enable a periodic task. The task will run according to its configured schedule on its assigned nodes from the next scheduling tick onwards.

Requires admin authentication and the policy action periodictask_write.

Parameters:

  • ptaskid – path component, the numeric id of the periodic task.

Status Codes:

  • 200 OK – id of the task in result.value.

  • 404 Not Found – no periodic task with that id exists.

POST /periodictask/disable/(ptaskid)

Disable a periodic task. The task definition is preserved but no new runs are scheduled until it is enabled again.

Requires admin authentication and the policy action periodictask_write.

Parameters:

  • ptaskid – path component, the numeric id of the periodic task.

Status Codes:

  • 200 OK – id of the task in result.value.

  • 404 Not Found – no periodic task with that id exists.

DELETE /periodictask/(ptaskid)

Delete a periodic task definition.

Requires admin authentication and the policy action periodictask_write.

Parameters:

  • ptaskid – path component, the numeric id of the periodic task.

Status Codes:

  • 200 OK – id of the deleted task in result.value.

  • 404 Not Found – no periodic task with that id exists.