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).

OperationCall
List scheduled tasksGET /tasksFree
Get scheduled taskGET /tasks/{taskId}Free
Create scheduled taskPOST /tasksFree
Update scheduled taskPATCH /tasks/{taskId}Free
Delete scheduled taskDELETE /tasks/{taskId}Free
Run scheduled taskPOST /tasks/{taskId}/runBilled
List scheduled task runsGET /tasks/{taskId}/runsFree

List scheduled tasks

GET/tasksFree

Every scheduled task of the workspace: its message, schedule, state, next and last run.

MCP tool list_scheduled_tasks

Request
curl https://app.semchat.io/api/v1/tasks \
  -H "Authorization: Bearer sk_live_…"

Answers 200 with { "data": … }.

Get scheduled task

GET/tasks/{taskId}Free

One scheduled task.

MCP tool get_scheduled_task

ArgumentTypeDescription
taskIdin the pathstringIts id.
Request
curl https://app.semchat.io/api/v1/tasks/{taskId} \
  -H "Authorization: Bearer sk_live_…"

Answers 200 with { "data": … }.

Create scheduled task

POST/tasksFree

Create 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

ArgumentTypeDescription
namerequiredstringThe task’s name, as the list shows it.1–120 characters
promptrequiredstringThe 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
schedulerequiredstring | nullWhen 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).
timezonerequiredstringThe time zone its times are in, e.g. "Europe/Paris".
site_idoptionalstring | nullThe site it’s about, for the list (null: none). Defaults to the first site its message names.
Request
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

PATCH/tasks/{taskId}Free

Change 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

ArgumentTypeDescription
taskIdin the pathstringIts id.
nameoptionalstringThe task’s name, as the list shows it.1–120 characters
promptoptionalstringThe 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
scheduleoptionalstring | nullWhen 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).
timezoneoptionalstringThe time zone its times are in, e.g. "Europe/Paris".
site_idoptionalstring | nullThe site it’s about, for the list (null: none). Defaults to the first site its message names.
statusoptionalstring"paused": it stops running; "active": it resumes (its error count is cleared).active | paused
Request
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

DELETE/tasks/{taskId}Free

Delete 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

ArgumentTypeDescription
taskIdin the pathstringIts id.
Request
curl -X DELETE https://app.semchat.io/api/v1/tasks/{taskId} \
  -H "Authorization: Bearer sk_live_…"

Answers 204 with { "data": … }.

Run scheduled task

POST/tasks/{taskId}/runBilled

Run 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

ArgumentTypeDescription
taskIdin the pathstringIts id.
Request
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

GET/tasks/{taskId}/runsFree

A scheduled task’s last runs, newest first: each one’s state, its conversation, its title and recap.

MCP tool list_scheduled_task_runs

ArgumentTypeDescription
taskIdin the pathstringIts id.
Request
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.

Ready to get your site off the ground?

Ask your first question - semchat replies with a clear action plan in seconds.

Free · no sign-up · takes 5 seconds