Home API Reference Tasks API

Tasks API

API Reference tasks scheduler cron api crud schedule nodeId taskType actionPayload cronString enabled

Full CRUD reference for the scheduled task system. Create, read, update, and delete cron-based tasks.

The Tasks API manages scheduled jobs that run on a cron expression schedule. Tasks are stored in a dedicated SQLite database (TASK_DB_PATH, default tasks.db). All endpoints are mounted at /api/tasks.

Data Model

id (int)

Auto-incremented primary key.

nodeId (str, required)

Target node ID, e.g. !aabbccdd or ^all.

taskType (str, required)

Type of action to perform. Interpreted by task_scheduler.py.

actionPayload (str, optional)

Task-specific data (e.g. message text, command string).

cronString (str, required)

Standard cron expression. Example: */5 * * * * (every 5 minutes).

enabled (bool)

Whether the task is active. Default: true.

createdAt (str)

ISO timestamp, set by SQLite on insert.

updatedAt (str)

ISO timestamp, automatically updated on change.

Create Task

POST /api/tasks/

POST /api/tasks/
Content-Type: application/json

{
  "nodeId": "^all",
  "taskType": "send_message",
  "actionPayload": "Good morning mesh!",
  "cronString": "0 8 * * *",
  "enabled": true
}

Returns HTTP 201 with the full task object including id, createdAt, and updatedAt.

{
  "id": 7,
  "nodeId": "^all",
  "taskType": "send_message",
  "actionPayload": "Good morning mesh!",
  "cronString": "0 8 * * *",
  "enabled": true,
  "createdAt": "2024-01-15 08:00:00",
  "updatedAt": "2024-01-15 08:00:00"
}

List All Tasks

GET /api/tasks/

Returns all tasks ordered by createdAt DESC.

GET /api/tasks/
→ Array of TaskInDB objects

Get Single Task

GET /api/tasks/{task_id}

GET /api/tasks/7
→ TaskInDB object, or 404 if not found

Update Task

PUT /api/tasks/{task_id}

Partial update — only fields included in the request body are changed. At least one field must be provided.

PUT /api/tasks/7
Content-Type: application/json

{
  "enabled": false
}

Returns the updated task object. Returns 404 if the task does not exist, 400 if no fields were provided.

Delete Task

DELETE /api/tasks/{task_id}

DELETE /api/tasks/7
→ HTTP 204 No Content

Returns 404 if not found.

Node Sensors (Deprecated Stub)

GET /api/tasks/sensors/{node_id}

This endpoint is marked deprecated in the code. It returns a hardcoded list of example sensors and is not connected to real node data. Do not build integrations against it.

Cron Expression Reference

Expression	Meaning
`* * * * *`	Every minute
`/5 * * *`	Every 5 minutes
`0 * * * *`	Every hour on the hour
`0 8 * * *`	Every day at 08:00
`0 8 * * 1`	Every Monday at 08:00
`0 8,20 * * *`	Every day at 08:00 and 20:00
`0 0 1 * *`	First day of every month at midnight

Error Responses

201

Task created successfully

204

Task deleted successfully (no body)

400

No update data provided / database integrity error

404

Task with given ID not found

500

Database connection or execution error — detail field contains the SQLite error

System & Config API Web Serial API