Bot schedules and wake

A bot runs when something starts it: you, a trigger, a chat message, or a schedule. A schedule is a scheduler job that runs the bot's saved workflow. You can create one from outside, or let the bot create its own.

Schedule a bot from outside

Over REST, POST /v1/schedules takes a saved workflow or bot id and either a cron expression or @once with run_at:

curl -s -X POST https://api.plungeai.com/v1/schedules \
  -H "Authorization: Bearer $PLUNGE_API_KEY" -H 'Content-Type: application/json' \
  -d '{"name":"Morning digest","workflow_id":"<bot id>","schedule":"0 9 * * 1-5","timezone":"America/Los_Angeles","parameters":{"deliver":["slack"]}}'

A one-time run removes itself after it fires:

curl -s -X POST https://api.plungeai.com/v1/schedules \
  -H "Authorization: Bearer $PLUNGE_API_KEY" -H 'Content-Type: application/json' \
  -d '{"name":"One-off report","workflow_id":"<bot id>","schedule":"@once","run_at":"2026-10-06T09:00:00Z"}'

Field	Meaning
`schedule`	A cron expression, or `@once` together with `run_at`.
`run_at`	ISO-8601 time with a UTC offset, in the future. Required for `@once`. Refused with `run_at_required` or `run_at_past` otherwise.
`timezone`	The IANA zone the cron is read in. Default UTC.
`ends_at`	ISO-8601 time or ms epoch after which the schedule stops. `PATCH` with `ends_at: null` clears it.
`parameters.deliver`	Where each result goes (below).
`parameters.input`	The per-run input.

The same operations are on MCP (plungeai_schedule) and the CLI (schedules create, --cron @once --at <iso>, --ends-at); see REST, MCP and CLI.

Let the bot schedule itself

List schedule in the bot's allowed_tools. The tool works on the bot's own jobs only:

Action	Input	Does
`create`	`name`, `cron`, `timezone?`, `prompt?`, `deliver?`, `ends_at?`	A recurring job. The model writes the 5-field cron and the reply echoes the schedule in words, so you can check it said what you asked.
`create` with `cron: "@once"`	`run_at`	One run at a clock time. Refused without a UTC offset.
`wake`	`in`, `note?`	One later run after a delay (`10m`, `2h`, `1d`; at least 60 s). The note becomes the run's input.
`list`		The bot's jobs with ids, the schedule in words and the next run.
`pause`, `resume`, `delete`	`id`	By job id.
`run_now`	`id`, `input?`	Fires a job once, now.

A bot holds at most 50 active jobs. ends_at retires a job after that time. With no timezone the job uses the user's zone, otherwise UTC.

The class of a schedule call is by action: delete is delete, list is read, the rest are write. Under posture: read_only only list runs.

Wake

A wake re-runs the bot once, later, without touching its schedule. The bot calls schedule with action: wake; from outside, POST /v1/schedules/{id}/wake does the same:

curl -s -X POST https://api.plungeai.com/v1/schedules/<id>/wake \
  -H "Authorization: Bearer $PLUNGE_API_KEY" -H 'Content-Type: application/json' \
  -d '{"note":"the inbox has new mail","in":"10m"}'

note becomes the run's input. in is seconds or a string like "90s", "10m", "2h"; left out, the wake fires on the scheduler's next tick.
A pending wake is re-timed, never stacked, so repeated wakes leave one job.
A schedule with no saved workflow (a heartbeat) cannot be woken.

Behind a wake is the scheduler's runAgain: it creates one @once job for the bot.

One-time jobs

An @once job fires once at its run_at, then deletes itself. A failed run may retry five minutes later first; the job is deleted on the final failure or on success. Because the job deletes itself, an outbound hook on it receives the run's last event and is then gone.

Deliver the result

parameters.deliver is a list of {channel, chat_id?, to?}. A bare channel name such as "slack" means the owner's own account.

Channel	Target
`inapp`	The Studio inbox.
`email`	The owner's registered address; other addresses must be confirmed recipients.
`slack`, `telegram`, `discord`	`chat_id`.
`whatsapp`	`to` (a phone number) and the sending `phone_number_id`.
`teams`	`chat_id`, a Microsoft Graph chat id.

Delivery is fenced by the owner's pairing and a per-channel length cap. Any other channel is 422 invalid_params and nothing is created.

[SILENT]: when a run's result is exactly [SILENT], or starts with it, the scheduler delivers to no channel and strips the marker from what it stores. A bot emits it when nothing is worth reporting. A run held for approval is never silent.
Threads: a delivery target may carry the reply or thread id of its channel, so the answer lands in the originating thread.
Retries: a failed delivery of a completed run is retried about 1 minute and then about 5 minutes later (three sends in all), then marked failed with an in-app notice.
Local bots: a job for a bot that runs on the owner's machine is skipped cleanly, with one notice, when that machine is offline.

Run history

GET /v1/schedules/{id}/runs lists the runs; GET /v1/schedules/{id} returns the schedule with its ten latest. A run has status, started_at, ended_at, duration_ms, execution_id and error. POST /v1/schedules/{id}/run runs it now and returns the execution_id, which POST /v1/executions/{id}/cancel accepts. DELETE removes the schedule and keeps its history readable.