Queue and scheduled tasks API
21 endpoints (16 queue + 1 observability + 4 scheduled).
Queue (low-level)#
A thin wrapper over ARQ for clients that need to enqueue work directly. Most apps shouldn't — prefer the higher-level endpoints that enqueue internally.
| Method | Path | Purpose |
|---|---|---|
POST |
/v1/queue/jobs |
Submit a job. |
GET |
/v1/queue/jobs/{job_id} |
Status. |
POST |
/v1/queue/jobs/{job_id}/cancel |
Try to cancel. |
GET |
/v1/queue/jobs |
List your jobs. |
GET |
/v1/queue/depth |
Queue depth metrics. |
POST |
/v1/queue/hitl/{request_id}/approve |
Approve a HITL-gated job. |
POST |
/v1/queue/hitl/{request_id}/reject |
Reject. |
GET |
/v1/queue/hitl |
List pending HITL requests. |
GET |
/v1/queue/correlation/{correlation_id} |
All jobs sharing a correlation id. |
| ... | (additional admin / introspection paths under /v1/queue/) |
... |
HITL = "human-in-the-loop". Some plugin tool calls are flagged for approval; they enqueue a queued job that waits for human approval before running.
Observability#
| Method | Path | Purpose |
|---|---|---|
GET |
/v1/queue/observability/... |
Aggregated metrics for the queue (admin). |
Scheduled tasks#
| Method | Path | Purpose |
|---|---|---|
GET |
/v1/scheduled-tasks |
List your scheduled tasks. |
POST |
/v1/scheduled-tasks |
Create. |
PATCH |
/v1/scheduled-tasks/{task_id} |
Update. |
DELETE |
/v1/scheduled-tasks/{task_id} |
Remove. |
POST body#
jsonc
{
"name": "Weekly status update",
"schedule": "0 9 * * MON", // crontab
"timezone": "Europe/Amsterdam",
"action": "send_message",
"args": {
"room_id": "room-…",
"content": { "msgtype": "swp.text", "body": "Monday status check" }
},
"enabled": true
}
Supported actions:
send_message— bot-style scheduled posts.trigger_ai— engage an AI in a room with a prompt.run_query— execute a stored notes query and post the results.
Custom actions can be plugin-provided.