API REFERENCE

The Scheduled Tasks API

The endpoints behind the My-tasks panel. Users create tasks from chat, and these routes let your app read, mark seen, edit, or cancel them from your own UI.

A scheduled task is work the agent runs later, on its own. One-off tasks fire once at an ISO timestamp, recurring tasks fire on a 5-field cron in a named IANA timezone. Each run happens unattended under a freshly re-signed copy of the user's identity, and the result surfaces on the user's next visit. These endpoints expose the same list the widget's My-tasks panel shows.

Scheduling is a signed-mode feature. Every call needs a signed user_context (send it in the X-Era-User header, URL-encoded), or the request is rejected with SIGNED_IDENTITY_REQUIRED.

The task object

Every endpoint returns tasks in this shape:

Field	Type	Description
`id`	string	Task identifier.
`title`	string	Short label the agent gave the task when it was created.
`prompt`	string	The instruction the agent runs at fire time.
`schedule_type`	"one_off" \| "recurring"	Whether the task fires once or repeats.
`run_at`	string (ISO 8601)	For one-off tasks, when it fires. Null for recurring.
`cron`	string	For recurring tasks, a 5-field cron expression. Null for one-off.
`timezone`	string (IANA)	The zone the schedule is evaluated in, e.g. "Asia/Riyadh".
`max_runs`	int	How many times a recurring task may fire. 0 means unlimited.
`run_count`	int	How many times it has fired so far.
`status`	string	One of the statuses below.
`last_result`	string \| null	A short summary of the most recent run's output.
`seen`	boolean	Whether the user has acknowledged the latest result in the panel.
`next_run`	string (ISO 8601) \| null	The next scheduled fire time, computed from cron + timezone.

Status values:

Field	Type	Description
`scheduled`	status	Waiting for its next fire time.
`running`	status	Currently executing a run.
`completed`	status	A one-off task that has fired, or a recurring task that hit max_runs.
`cancelled`	status	Stopped by the user or your app before completing.
`failed`	status	The last run errored (for example, budget exhausted).

Tasks are created from inside chat, not from these endpoints. The agent calls the reserved tools schedule_task, list_scheduled_tasks, update_scheduled_task, and cancel_scheduled_task. These HTTP routes are for reading and managing what already exists.

List tasks

GET/v1/scheduled-tasks

Returns the tasks owned by the user in the signed identity, newest first.

bash

curl https://eerraa.online/v1/scheduled-tasks \
  -H "Authorization: Bearer era_your_project_key" \
  -H "X-Era-User: %7B%22id%22%3A%22u_42%22%2C%22_ts%22%3A1735689600%2C%22_sig%22%3A%22a1b2c3...%22%7D"

json

{
  "tasks": [
    {
      "id": "task_7a1",
      "title": "Weekly summary",
      "prompt": "Summarize this week's open tickets and email me.",
      "schedule_type": "recurring",
      "run_at": null,
      "cron": "0 9 * * 1",
      "timezone": "Asia/Riyadh",
      "max_runs": 0,
      "run_count": 3,
      "status": "scheduled",
      "last_result": "6 tickets open, summary sent.",
      "seen": false,
      "next_run": "2026-09-07T06:00:00Z"
    }
  ]
}

Mark results seen

POST/v1/scheduled-tasks

Acknowledges the latest run results so the My-tasks panel can clear its unread badge. Send the task ids the user has now seen. This is the one POST on the resource, and it does not create tasks.

Field	Type	Description
`seen`required	string[]	Task ids to mark as acknowledged.
`user_context`required	object	Signed identity (or send it in the X-Era-User header).

bash

curl -X POST https://eerraa.online/v1/scheduled-tasks \
  -H "Authorization: Bearer era_your_project_key" \
  -H "Content-Type: application/json" \
  -H "X-Era-User: %7B%22id%22%3A%22u_42%22%2C%22_ts%22%3A...%2C%22_sig%22%3A%22...%22%7D" \
  -d '{ "seen": ["task_7a1"] }'

json

{ "ok": true, "seen": ["task_7a1"] }

Update a task

PATCH/v1/scheduled-tasks

Edits an existing task. Pass the task id plus only the fields you want to change. You can retime a one-off task, change a cron or timezone, raise or lower max_runs, or pause it.

Field	Type	Description
`id`required	string	The task to update.
`run_at`	string (ISO 8601)	New fire time for a one-off task.
`cron`	string	New 5-field cron for a recurring task.
`timezone`	string (IANA)	New zone to evaluate the schedule in.
`max_runs`	int	New run cap. 0 means unlimited.
`status`	"scheduled" \| "cancelled"	Set to "cancelled" to pause, or back to "scheduled" to resume.

bash

curl -X PATCH https://eerraa.online/v1/scheduled-tasks \
  -H "Authorization: Bearer era_your_project_key" \
  -H "Content-Type: application/json" \
  -H "X-Era-User: %7B...signed...%7D" \
  -d '{ "id": "task_7a1", "cron": "0 8 * * 1", "timezone": "Asia/Riyadh" }'

json

{
  "id": "task_7a1",
  "cron": "0 8 * * 1",
  "timezone": "Asia/Riyadh",
  "status": "scheduled",
  "next_run": "2026-09-07T05:00:00Z"
}

Cancel a task

DELETE/v1/scheduled-tasks

Cancels a task for good. Pass the task id. A cancelled task never fires again and drops off the active list.

bash

curl -X DELETE "https://eerraa.online/v1/scheduled-tasks?id=task_7a1" \
  -H "Authorization: Bearer era_your_project_key" \
  -H "X-Era-User: %7B...signed...%7D"

json

{ "deleted": true, "id": "task_7a1" }

Recurring runs are budget-aware. If a project hits its monthly token budget, an unattended run fails rather than overspending, and the task shows failed until the budget resets or you raise it.

PREVIOUSKnowledge API NEXTMCP OAuth API