DocumentationAPI reference
Scheduled tasks
Scheduled tasks: create, change, run now, and read their runs.
Every operation below is also an MCP tool, under the same name. Free operations cost nothing; Billed ones use the workspace’s credits, as in the app (What it costs).
| Operation | Call | |
|---|---|---|
| List scheduled tasks | GET /tasks | Free |
| Get scheduled task | GET /tasks/{taskId} | Free |
| Create scheduled task | POST /tasks | Free |
| Update scheduled task | PATCH /tasks/{taskId} | Free |
| Delete scheduled task | DELETE /tasks/{taskId} | Free |
| Run scheduled task | POST /tasks/{taskId}/run | Billed |
| List scheduled task runs | GET /tasks/{taskId}/runs | Free |
List scheduled tasks
/tasksFreeEvery scheduled task of the workspace: its message, schedule, state, next and last run.
MCP tool list_scheduled_tasks
curl https://app.semchat.io/api/v1/tasks \
-H "Authorization: Bearer sk_live_…"Answers 200 with { "data": … }.
Get scheduled task
/tasks/{taskId}FreeOne scheduled task.
MCP tool get_scheduled_task
| Argument | Type | Description |
|---|---|---|
taskIdin the path | string | Its id. |
curl https://app.semchat.io/api/v1/tasks/{taskId} \
-H "Authorization: Bearer sk_live_…"Answers 200 with { "data": … }.
Create scheduled task
/tasksFreeCreate a scheduled task: a message the assistant runs by itself on a schedule, as in the app’s Tasks.
- It starts active: its first run is at the schedule’s next time.
- Each run is a conversation of the workspace, billed like a chat message. An action that leaves semchat (publishing, posting) that its message asks for is done at once, as in any chat.
MCP tool create_scheduled_task
| Argument | Type | Description |
|---|---|---|
namerequired | string | The task’s name, as the list shows it.1–120 characters |
promptrequired | string | The message the assistant runs each time, written as in the chat. It may name a site (« /site:example.com »: its data and connectors), a skill (« /<skill-id> »), an email address (« /email:paul@example.com »), a Discord channel (« /discord:<id> »), a Slack or Notion account (« /slack:<id> », « /notion:<id> »).1–8000 characters |
schedulerequired | string | null | When it runs: { kind: "daily", time: "08:00" }, { kind: "weekly", days: ["mon", "thu"], time: "08:00" }, { kind: "monthly", day: 1, time: "08:00" } (a shorter month: its last day), or { kind: "hourly", every: 6 } (1, 2, 3, 4, 6, 8 or 12). |
timezonerequired | string | The time zone its times are in, e.g. "Europe/Paris". |
site_idoptional | string | null | The site it’s about, for the list (null: none). Defaults to the first site its message names. |
curl -X POST https://app.semchat.io/api/v1/tasks \
-H "Authorization: Bearer sk_live_…" \
-H "Content-Type: application/json" \
-d '{"name": "…", "prompt": "…", "schedule": "…", "timezone": "…"}'Answers 201 with { "data": … }.
Update scheduled task
/tasks/{taskId}FreeChange a scheduled task: its name, message, schedule, time zone or site, or pause and resume it (status).
- Only its author, or the workspace’s owner or an admin, can change, run or delete a task: 403 FORBIDDEN otherwise.
- Only the fields given change; at least one is required. A new schedule or time zone, or a resume, moves the next run to the schedule’s next time from now.
MCP tool update_scheduled_task
| Argument | Type | Description |
|---|---|---|
taskIdin the path | string | Its id. |
nameoptional | string | The task’s name, as the list shows it.1–120 characters |
promptoptional | string | The message the assistant runs each time, written as in the chat. It may name a site (« /site:example.com »: its data and connectors), a skill (« /<skill-id> »), an email address (« /email:paul@example.com »), a Discord channel (« /discord:<id> »), a Slack or Notion account (« /slack:<id> », « /notion:<id> »).1–8000 characters |
scheduleoptional | string | null | When it runs: { kind: "daily", time: "08:00" }, { kind: "weekly", days: ["mon", "thu"], time: "08:00" }, { kind: "monthly", day: 1, time: "08:00" } (a shorter month: its last day), or { kind: "hourly", every: 6 } (1, 2, 3, 4, 6, 8 or 12). |
timezoneoptional | string | The time zone its times are in, e.g. "Europe/Paris". |
site_idoptional | string | null | The site it’s about, for the list (null: none). Defaults to the first site its message names. |
statusoptional | string | "paused": it stops running; "active": it resumes (its error count is cleared).active | paused |
curl -X PATCH https://app.semchat.io/api/v1/tasks/{taskId} \
-H "Authorization: Bearer sk_live_…" \
-H "Content-Type: application/json" \
-d '{"name": "…"}'Answers 200 with { "data": … }.
Delete scheduled task
/tasks/{taskId}FreeDelete a scheduled task. Its past runs and their conversations stay.
- Only its author, or the workspace’s owner or an admin, can change, run or delete a task: 403 FORBIDDEN otherwise.
MCP tool delete_scheduled_task
| Argument | Type | Description |
|---|---|---|
taskIdin the path | string | Its id. |
curl -X DELETE https://app.semchat.io/api/v1/tasks/{taskId} \
-H "Authorization: Bearer sk_live_…"Answers 204 with { "data": … }.
Run scheduled task
/tasks/{taskId}/runBilledRun a scheduled task now, as the app’s « Run now »: one run, its schedule unchanged.
- Only its author, or the workspace’s owner or an admin, can change, run or delete a task: 403 FORBIDDEN otherwise.
- Answers at once with the run’s id; the run goes on in the background: read list_scheduled_task_runs for its conversation and recap.
- 409 CONFLICT while one of its runs is going; 402 INSUFFICIENT_TOKENS without credits.
MCP tool run_scheduled_task
| Argument | Type | Description |
|---|---|---|
taskIdin the path | string | Its id. |
curl -X POST https://app.semchat.io/api/v1/tasks/{taskId}/run \
-H "Authorization: Bearer sk_live_…"Answers 202 with { "data": … }.
List scheduled task runs
/tasks/{taskId}/runsFreeA scheduled task’s last runs, newest first: each one’s state, its conversation, its title and recap.
MCP tool list_scheduled_task_runs
| Argument | Type | Description |
|---|---|---|
taskIdin the path | string | Its id. |
curl https://app.semchat.io/api/v1/tasks/{taskId}/runs \
-H "Authorization: Bearer sk_live_…"Answers 200 with { "data": … }.
A question this doesn’t answer? Write to us.

