Schedules
Documentation for Schedules
Base path: /api/v1/schedules
Schedules represent recurring execution plans for workflows powered by Temporal. You can list all schedules for the authenticated user and update the input parameters for a scheduled workflow.
To create, pause/resume, or delete a schedule, use the workflow-specific schedule endpoints under
/api/v1/workflows/:workflowId/schedule. See workflows.md.
All endpoints require JWT authentication and an x-active-org header.
Endpoints Overview
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /api/v1/schedules | JWT | List all schedules for the authenticated user |
| PUT | /api/v1/schedules/:scheduleId/workflow-params | JWT | Update schedule inputs and environment variables |
GET /api/v1/schedules
Lists all workflow schedules owned by the authenticated user within the active organization.
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
page | number | 1 | Page number (min: 1) |
limit | number | 20 | Items per page (min: 1, max: 100) |
search | string | – | Search by workflow name (case-insensitive substring) |
Response 200 OK
Schedule object fields:
| Field | Type | Description |
|---|---|---|
id | string (UUID) | Schedule ID |
workflowId | string (UUID) | ID of the associated workflow |
workflowName | string | null | Workflow name |
workflowDescription | string | null | Workflow description |
description | string | null | Human-readable schedule description |
definition | object | null | Schedule specification object (see Schedule Definition below) |
isPaused | boolean | Whether the schedule is currently paused |
createdAt | string (ISO 8601) | When the schedule was created |
updatedAt | string (ISO 8601) | Last update time |
Schedule Definition Object
The definition field describes when the workflow runs:
| Field | Type | Description |
|---|---|---|
intervals | array | Interval-based schedules: [{ "every": "1h", "offset": "0" }] |
calendars | array | Calendar-based schedules (cron-like) |
timezone | string | null | IANA timezone string, e.g. "America/New_York" |
jitter | string | number | null | Random delay to spread load (duration string or seconds) |
startAt | string | null | ISO 8601 start datetime |
endAt | string | null | ISO 8601 end datetime |
description | string | null | Human-readable description |
Calendar entry fields: second, minute, hour, dayOfMonth, month, year, dayOfWeek — each accepts a single value, a range ({ start, end, step }), or an array of values.
PUT /api/v1/schedules/:scheduleId/workflow-params
Updates the input values and environment variables used when the schedule triggers the workflow. Changes are propagated to the Temporal schedule immediately.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
scheduleId | string (UUID) | Schedule ID |
Request Body (multipart/form-data)
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
inputs | JSON object | No | {} | Input values for the scheduled run (keyed by input name) |
envs | JSON object | No | {} | Environment variable overrides (string-to-string map) |
Response 200 OK
Errors
| Status | Reason |
|---|---|
404 Not Found | Schedule not found in DB or not found in Temporal |