Tasks (The Heartbeat)

Schedule and manage autonomous background agent tasks.

POST /v1/tasks

Schedule a new background task. The task runs The Soul on the specified cron schedule with full tenant-wide memory access.

Request

curl -X POST https://api.brainstormrouter.com/v1/tasks \
  -H "Authorization: Bearer br_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "daily-summary",
    "prompt": "Summarize key findings from today and store takeaways in archival memory.",
    "schedule": "0 18 * * *",
    "timezone": "America/New_York",
    "model": "anthropic/claude-sonnet-4-5"
  }'

Body parameters

Parameter	Type	Required	Description
name	string	Yes	Human-readable task name
prompt	string	Yes	The prompt The Soul executes each run
schedule	string	Yes	Cron expression (5-6 fields)
model	string	No	provider/model format (default: system default)
timezone	string	No	IANA timezone for the cron expression
conversation_id	string	No	Pin executions to a single session
description	string	No	Optional task description

Cron expression format

Standard 5-field cron (minute hour day month weekday):

Expression	Meaning
0	Every hour
/15 *	Every 15 minutes
0 9 1-5	Weekdays at 9 AM
0 18 *	Daily at 6 PM
0 0 1	First of every month

Response

{
  "task": {
    "id": "cron_abc123",
    "name": "daily-summary",
    "enabled": true,
    "schedule": {
      "type": "cron",
      "expression": "0 18 * * *",
      "timezone": "America/New_York"
    },
    "prompt": "Summarize key findings from today...",
    "model": "anthropic/claude-sonnet-4-5",
    "created_at": "2026-02-25T12:00:00.000Z",
    "updated_at": "2026-02-25T12:00:00.000Z",
    "state": {
      "next_run_at": "2026-02-25T23:00:00.000Z",
      "last_run_at": null,
      "last_status": null,
      "consecutive_errors": 0
    }
  }
}

---

GET /v1/tasks

List all tasks for the authenticated tenant.

Request

curl https://api.brainstormrouter.com/v1/tasks \
  -H "Authorization: Bearer br_live_..."

Response

{
  "tasks": [
    {
      "id": "cron_abc123",
      "name": "daily-summary",
      "enabled": true,
      "schedule": { "type": "cron", "expression": "0 18 * * *" },
      "state": {
        "next_run_at": "2026-02-25T23:00:00.000Z",
        "last_run_at": "2026-02-24T23:00:00.000Z",
        "last_status": "ok",
        "consecutive_errors": 0
      }
    }
  ],
  "total": 1
}

---

DELETE /v1/tasks/:id

Cancel and remove a task.

Request

curl -X DELETE https://api.brainstormrouter.com/v1/tasks/cron_abc123 \
  -H "Authorization: Bearer br_live_..."

Response

{
  "ok": true,
  "id": "cron_abc123"
}

Error responses

Status	Description
400	Invalid request (missing fields, bad cron expression)
403	Insufficient permissions (requires config.write for POST/DELETE, config.read for GET)
404	Task not found
500	Server error