Create a schedule
POST /schedules
Requires: tasks.schedule.write, tasks.start
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 ”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
NO_AGENTS — the template names no agents; CRON_INVALID — the schedule cannot run as written: an unparsable expression, an unknown timezone, a cadence or field outside what is allowed, or a combination with no future occurrence.
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
AGENT_NOT_ALLOWED — your roles do not allow that agent; AGENT_GRANT_FORBIDDEN — it would grant a permission you do not hold yourself.
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
HOST_NOT_FOUND or PROJECT_NOT_FOUND — the runner or repository named by the template does not exist in this workspace.
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
The runner cannot serve the roster as written: AGENT_MISSING, AGENT_KIND_UNSUPPORTED, MODEL_UNSUPPORTED, EFFORT_UNSUPPORTED, or SHARED_HOST_MANAGED_ENGINE_ONLY for an engine kind a shared runner offers neither as managed nor as a workspace-connected account.
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
AI_ACCOUNT_NOT_AVAILABLE — a listed AI account is unknown or not usable by this person; SECRETARY_REQUIRED — the roster needs a secretary and the selection is absent or not on the roster. A malformed id fails request parsing with 400 before reaching this; SECRETARY_NOT_ENFORCEABLE — the selection cannot be enforced: the chosen agent cannot be held to the role, the roster ids are too large to police, or the runner does not advertise the secretary capability at all; BUILT_IN_AGENT — an agent carries the built-in marker, which only Moondeck sets; AVATAR_RESERVED — an agent wears an avatar reserved for the built-in Astronaut: house bot pxlbot:901:…, or a house background colour such as midnight.
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