Schedules
Manage cron schedules for workflows via the API.
Endpoints for schedules under /api/v1/schedules.
Endpoints
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/schedules | List schedules |
| POST | /api/v1/schedules | Create a schedule |
| PATCH | /api/v1/schedules/{id} | Update a schedule |
| DELETE | /api/v1/schedules/{id} | Delete a schedule |
| POST | /api/v1/schedules/{id}/run | Run a schedule now |
| POST | /api/v1/schedules/process-due | Process due schedules (worker) |
Create and manage
GET /api/v1/schedules returns { schedules[] } enriched with execution state. Workspace keys with
workspace.secret.read or workspace.write receive the complete schedule. Personal, Copilot,
Viewer, organization-derived, and oversight reads receive workspace-safe.v1: the response keeps
schedule identity, workspace/workflow ids, frequency, lifecycle, run counters, next/last run,
enabled state, and execution state, but replaces title, description, cron, time, timezone,
and command prompt with [redacted] and omits startAt. Every safe row includes:
{ "redaction": { "applied": true, "projection": "safe-content", "contractVersion": "workspace-safe.v1" } }
Clients must use that discriminator instead of treating redacted strings or omitted fields as the stored schedule configuration.
POST /api/v1/schedules attaches a cron schedule to a workflow:
| Field | Type | Notes |
|---|---|---|
workflowId | string | Required; the workflow must be deployed |
title, description | string | Optional labels |
cron | string | Standard 5-field cron expression |
timezone | string | IANA timezone (for example America/New_York) |
startAt | string | ISO start time |
lifecycle | recurring | limited | One-shot vs recurring |
maxRuns | number | Cap for limited schedules |
enabled | boolean | Pause without deleting |
If the workflow is not deployed the request returns 409. Success returns 201 with the schedule
plus a runNowUrl. PATCH /api/v1/schedules/{id} updates fields; DELETE returns
{ deleted: true }. POST /api/v1/schedules/{id}/run runs the schedule immediately (accepts
Idempotency-Key) and returns 201 with { run, schedule, statusUrl, cancelUrl }.
Processing due schedules
POST /api/v1/schedules/process-due processes all schedules due at now (optional { now } ISO
body, defaults to server time) and returns a summary. This is the endpoint an external cron can
call instead of running the long-lived scheduler worker.