Create Schedule

Create a new schedule in the scheduler blob revision. The schedule is registered with the underlying scheduling service immediately and begins firing according to its configuration once it becomes active.

POST `/revisions/:id/data/command` (Command: `create_schedule`)

Request Body

Parameter	Type	Required	Description
`command`	string	Yes	Must be `create_schedule`.
`alias`	string	No	Optional stable name for the schedule. 6–42 chars, lowercase (`a`–`z`, `0`–`9`, `_`, `-`), unique in the revision.
`description`	string	No	What the schedule is for, at most 256 characters. Every fire sends it as the new execution’s `description`.
`repeat`	string	Yes	Either `one_time` or `recurring_cron`.
`timezone`	string	Yes	IANA timezone name (e.g. `America/New_York`, `UTC`).
`invocation_target_type`	string	Yes	Must be `workflow`.
`invocation_target`	object	Yes	Where and what to run when the schedule fires — `target` (`org`, `blob`, `revision` — a uuid or `default` — and `session`), `workflow` and `input_data`. See Invocation Targets for field details and the pinned-vs-following distinction.
`cron_expression`	string	Conditional	Required when `repeat` is `recurring_cron`. Six-field AWS cron expression.
`invocation_time`	string	Conditional	Required when `repeat` is `one_time`. ISO 8601 datetime without timezone suffix (e.g. `2026-05-01T14:30:00`), interpreted in the schedule’s `timezone`.
`enabled`	boolean	No	Whether the schedule is initially enabled. Defaults to `true`.
`start_date`	string	No	ISO 8601 UTC datetime before which the schedule does not fire.
`end_date`	string	No	ISO 8601 UTC datetime after which the schedule does not fire.

The schedule’s own alias names the schedule itself. It is unrelated to invocation_target.workflow.definition, which names the separate workflow definition the schedule invokes when it fires — the two keys sit side by side below but identify different objects. See Alias Grammar for the character rules, length limits, and the id-shape restriction — an alias may not be shaped like a UUID.

Response

Parameter	Type	Description
`schedule`	object	The created schedule object.

The schedule records the user_id of the user who created it. Scheduled executions this schedule triggers run as that user — which is what lets those executions, and any writes they make, be attributed back to a real identity.

Errors

Status	Error	Cause
400	`invalid_request_body`	An alias outside the grammar, an unknown field — at the top level, in `invocation_target` or in its `target` — a `target` part that is blank or over 64 characters, a `description` over 256 characters, or a following target (`target.revision` is `default`) naming its `session` by id.
400	`alias_in_use`	The alias is already taken in this revision.
400	`invalid_invocation_target`	`target.blob` is an alias with no `target.org`, or `workflow.definition` is an id where the definition follows `default`.
400	`invalid_workflow_reference`	A malformed `workflow`.
400	`invalid_definition_category`	`workflow.definition` is a definition id naming a `playground` definition the caller can reach.
403	`forbidden`	Any failure to resolve or reach the target (`target.org`, `target.blob`, `target.revision`, `target.session`) or the `workflow` source — identical whatever the cause.

Example (Recurring Cron)

{
  "command": "create_schedule",
  "alias": "morning-digest",
  "description": "Daily report for the morning digest.",
  "repeat": "recurring_cron",
  "cron_expression": "0 9 * * ? *",
  "timezone": "America/New_York",
  "enabled": true,
  "invocation_target_type": "workflow",
  "invocation_target": {
    "target": {
      "blob": "5b0e7c2a-3f61-4d9b-8a47-2c9e1f6d0b38",
      "revision": "default",
      "session": "scheduled_runs"
    },
    "workflow": {"definition": "daily-report"},
    "input_data": []
  }
}

{
  "status": "success",
  "schedule": {
    "id": "sched-001",
    "alias": "morning-digest",
    "description": "Daily report for the morning digest.",
    "revision_id": "rev-scheduler-001",
    "created_at": "2026-04-07T12:00:00Z",
    "modified_at": "2026-04-07T12:00:00Z",
    "auth_target": "user",
    "auth_target_id": "user-001",
    "enabled": true,
    "repeat": "recurring_cron",
    "cron_expression": "0 9 * * ? *",
    "invocation_time": null,
    "timezone": "America/New_York",
    "start_date": null,
    "end_date": null,
    "state": "active",
    "invocation_target_type": "workflow",
    "invocation_target": {
      "target": {
        "blob": "5b0e7c2a-3f61-4d9b-8a47-2c9e1f6d0b38",
        "revision": "default",
        "session": "scheduled_runs"
      },
      "workflow": {"definition": "daily-report"},
      "input_data": []
    }
  }
}

This request’s target.session is an alias, because a default-following target must name its session that way — no session id survives a revision boundary, so the schema refuses a uuid-shaped target.session here. A target naming its blob by alias needs target.org alongside it:

"invocation_target": {
  "target": {
    "org": "acme-corp",
    "blob": "shared-procedures",
    "revision": "default",
    "session": "scheduled_runs"
  },
  "workflow": {"definition": "triage"},
  "input_data": []
}

Example (One-Time)

{
  "command": "create_schedule",
  "alias": "product-launch",
  "repeat": "one_time",
  "invocation_time": "2026-05-01T14:30:00",
  "timezone": "UTC",
  "invocation_target_type": "workflow",
  "invocation_target": {
    "target": {
      "blob": "5b0e7c2a-3f61-4d9b-8a47-2c9e1f6d0b38",
      "revision": "8f2a1c40-9d3e-4b17-9f0a-3c6f5b1d2e77",
      "session": "launch_day_runs"
    },
    "workflow": {"definition": "one-shot-job"},
    "input_data": ["payload"]
  }
}

{
  "status": "success",
  "schedule": {
    "id": "sched-002",
    "alias": "product-launch",
    "revision_id": "rev-scheduler-001",
    "created_at": "2026-04-07T12:05:00Z",
    "modified_at": "2026-04-07T12:05:00Z",
    "auth_target": "user",
    "auth_target_id": "user-001",
    "enabled": true,
    "repeat": "one_time",
    "cron_expression": null,
    "invocation_time": "2026-05-01T14:30:00",
    "timezone": "UTC",
    "start_date": null,
    "end_date": null,
    "state": "active",
    "invocation_target_type": "workflow",
    "invocation_target": {
      "target": {
        "blob": "5b0e7c2a-3f61-4d9b-8a47-2c9e1f6d0b38",
        "revision": "8f2a1c40-9d3e-4b17-9f0a-3c6f5b1d2e77",
        "session": "2c4b9e10-7a3d-4f58-9b61-0e8d3f5a7c29"
      },
      "workflow": {"definition": "one-shot-job"},
      "input_data": ["payload"]
    }
  }
}

This request pins its target: target.revision is a concrete uuid, so target.session is resolved once, at save time, and stored as the id it resolved to — the response carries that id, not the alias the request sent.

Overview

Workflow

Scheduler

ONNX

Create Schedule

POST `/revisions/:id/data/command` (Command: `create_schedule`)

Request Body

Response

Errors

Example (Recurring Cron)

Example (One-Time)

​POST /revisions/:id/data/command (Command: create_schedule)

​Request Body

​Response

​Errors

​Example (Recurring Cron)

​Example (One-Time)

POST `/revisions/:id/data/command` (Command: `create_schedule`)

Request Body

Response

Errors

Example (Recurring Cron)

Example (One-Time)