Update a schedule
PATCH /schedules/{id}
May require, depending on the request: tasks.schedule.write, tasks.schedule.manage.any
Payload shapes are not yet fully described. The endpoint, authentication and permissions are accurate; unconstrained JSON marks the shapes still awaiting extraction.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”Resource ULID.
Header Parameters
Section titled “Header Parameters ”Org scope: me or an org slug. Absent means the caller’s active/personal org. It selects the workspace used for permission checks and for most resource filters; operation-specific access rules still apply.
Request Body required
Section titled “Request Body required ”Shape not yet described.
Responses
Section titled “ Responses ”Successful response.
object
object
ULID
Five-field cron expression
IANA timezone the cron is evaluated in
What to do when the previous run is still going
What to do when a fire time was missed
Epoch milliseconds
Set when the system disabled it
Task this schedule clones on each run
object
ULID
When this run was scheduled to fire
What caused the run — a tick, or a manual run
Lifecycle state of the run
Task the run created, once it has one
Why the run did not start: a missed fire time, an overlapping previous run, the schedule having been paused, rescheduled or deleted, or a task left starting by a managed-runner restart. Prose, not an enum — do not branch on it.
Epoch milliseconds
The cron expression in prose
The next few fire times, derived at read time
CRON_INVALID, or the update was refused.
BAD_JSON — the body is not valid JSON, or INVALID_REQUEST — the decoded body does not match the route’s request schema.
object
object
Stable, machine-readable error code
Human-readable explanation
Present on 403 — the permission the caller lacked
Present on 402 — gated feature
Present on 402 — the plan’s cap
Present on 402 — the current plan
UNAUTHORIZED — missing or invalid token, or an org-scoped API key (only user-scoped keys are accepted).
object
object
Stable, machine-readable error code
Human-readable explanation
Present on 403 — the permission the caller lacked
Present on 402 — gated feature
Present on 402 — the plan’s cap
Present on 402 — the current plan
PLAN_LIMIT — the workspace’s plan does not include API access. Every API-key call can return this; session-token calls never do.
object
object
Stable, machine-readable error code
Human-readable explanation
Present on 403 — the permission the caller lacked
Present on 402 — gated feature
Present on 402 — the plan’s cap
Present on 402 — the current plan
SCHEDULE_NOT_YOURS — schedule reads are workspace-wide, so this is 403 rather than 404: you can see it, you just cannot change it.
FORBIDDEN (lacking the required permission) or SCOPE_REQUIRED (no workspace, or a membership change in progress).
object
object
Stable, machine-readable error code
Human-readable explanation
Present on 403 — the permission the caller lacked
Present on 402 — gated feature
Present on 402 — the plan’s cap
Present on 402 — the current plan
SCHEDULE_NOT_FOUND.
SCOPE_REQUIRED — the x-uai-org scope names a workspace that does not exist, or one the caller is not a member of. The two are deliberately indistinguishable: a 403 would confirm the workspace exists.
object
object
Stable, machine-readable error code
Human-readable explanation
Present on 403 — the permission the caller lacked
Present on 402 — gated feature
Present on 402 — the plan’s cap
Present on 402 — the current plan
SCOPE_REQUIRED — membership reconciliation required, or membership verification unavailable.
object
object
Stable, machine-readable error code
Human-readable explanation
Present on 403 — the permission the caller lacked
Present on 402 — gated feature
Present on 402 — the plan’s cap
Present on 402 — the current plan