Run a block on a schedule
create_scheduleStart firing a schedule block on a cron unattended by pinning a committed workspace version; preview without confirm, then confirm to create and quote the reported firing time.
Instructions
Starts firing a Schedule block on a cron, unattended. THIS is what makes a schedule real — setting schedule on the block only records the cadence in the workspace's content. Requires confirm=true; call without confirm first to preview. It pins the latest COMMITTED version (commit first if there isn't one — the error says so), and the plan decides the fastest allowed cadence: a free workspace is one schedule, hourly. On a free plan the firing time is offset by a fixed number of seconds so every workspace doesn't fire at once — the reply reports it, so quote the real time back to the user.
PINNING IS FROZEN, and that is the opposite of how deploy_endpoint behaves: an endpoint serves the live auto-save and picks up every edit at once, a schedule keeps running its commit. So editing a block the schedule fires changes nothing about tonight's run — that takes a new commit and a schedule pinned to it. Say this to the user when you create one; list_schedules reports canvasAheadOfPin once the two have parted company.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"workspaceId": "<workspaceId>",
"blockId": "<blockId>",
"cron": "<cron>"
},
"name": "create_schedule"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cron | Yes | Five-field cron, e.g. "0 9 * * *" (09:00 daily) or "*/15 * * * *". | |
| blockId | Yes | The Schedule block to fire, from get_workspace_content. | |
| confirm | No | Must be true to create. Omit/false returns a preview only. | |
| timeZone | No | IANA timezone the cron is read in, e.g. "Europe/Paris". Defaults to UTC. | |
| versionId | No | Workspace version to pin. Omit for the latest COMMITTED version — never the auto-save, which is where half-finished work lives. A workspace with no commit is rejected, with an explanation. | |
| workspaceId | Yes |