Automations API

Create and manage scheduled agent prompts; inspect per-run Pocket relay usage.

Base path: /api/scheduled-tasks. All routes require a valid X-Agent-Access-Tokenfor the task's agent. List requires a query agent_id.

OpenAPI tag

In Swagger UI these appear under the scheduled-tasks tag. The product UI labels them Automations.

POST/api/scheduled-tasksX-Agent-Access-Token

Create an automation. Returns the full row including id and next_run_at.

{
  "agent_id": "uuid",
  "prompt": "string (1–2000 chars)",
  "interval_seconds": 3600
}

Constraints: interval_seconds ∈ [60, 604800]. New jobs start with enabled=1 and next_run_at = now + interval.

GET/api/scheduled-tasks?agent_id={id}X-Agent-Access-Token

List automations for one agent, newest first. agent_id is required.

GET/api/scheduled-tasks/{id}X-Agent-Access-Token

Fetch one automation. 404 if missing or token does not own the agent.

PATCH/api/scheduled-tasks/{id}X-Agent-Access-Token

Partial update: enabled, prompt, and/or interval_seconds.

{
  "enabled": false,
  "prompt": "optional new prompt",
  "interval_seconds": 900
}

Changing interval_seconds resets next_run_at to now + new interval.

DELETE/api/scheduled-tasks/{id}X-Agent-Access-Token

Delete automation (204). Cascades scheduled_task_runs rows when FK is enforced.

GET/api/scheduled-tasks/{id}/relay-statsX-Agent-Access-Token

Last up to 10 runs with per-run relay_count, success flag, and aggregates.

{
  "total_relays_last_10_runs": 2,
  "avg_relays_per_run": 1.0,
  "runs": [
    {
      "started_at": 1710000000,
      "finished_at": 1710000012,
      "relay_count": 1,
      "success": true
    }
  ]
}

Scheduler behavior

Background loop in services/scheduler.py
~30s poll; runs due rows with enabled=1
Each run calls AIAgentService.chat(message=prompt, …)
Updates last_result / last_error, last_run_at, next_run_at, run_count