Scheduler API

All scheduler endpoints are relative to /api/scheduler.

Create or update a schedule

POST /api/scheduler/schedules

Creates a new schedule or updates an existing one (matched by name).

Request body:

{
  "name": "daily-report-schedule",
  "cronExpression": "0 0 9 * * MON-FRI",
  "zoneId": "America/New_York",
  "startWorkflowRequest": {
    "name": "daily_report_workflow",
    "version": 1,
    "input": {},
    "correlationId": "daily-report-${scheduledTime}"
  },
  "runCatchupScheduleInstances": false,
  "paused": false,
  "scheduleStartTime": 0,
  "scheduleEndTime": 0,
  "description": "Triggers the daily report workflow on weekday mornings"
}

Schedule fields:

Field	Type	Required	Default	Description
`name`	string	Yes	—	Unique schedule identifier
`cronExpression`	string	Yes	—	6-field Spring cron expression (second precision)
`zoneId`	string	No	`UTC`	IANA timezone for cron evaluation
`startWorkflowRequest`	object	Yes	—	Workflow trigger configuration (see below)
`runCatchupScheduleInstances`	boolean	No	`false`	Fire missed slots on scheduler restart
`paused`	boolean	No	`false`	Create in paused state
`scheduleStartTime`	long	No	—	Earliest fire time (epoch ms)
`scheduleEndTime`	long	No	—	Latest fire time (epoch ms)
`description`	string	No	—	Free-text description

startWorkflowRequest fields:

Field	Type	Required	Description
`name`	string	Yes	Workflow name
`version`	integer	No	Workflow version (latest if omitted)
`input`	object	No	Static input merged with auto-injected `_scheduledTime` and `_executedTime`
`correlationId`	string	No	Supports `${scheduledTime}` template variable
`taskToDomain`	object	No	Task-to-domain mapping
`priority`	integer	No	Execution priority (0-99)

Response: 200 OK — returns the saved WorkflowSchedule object.

Example using cURL

curl -X POST 'http://localhost:8080/api/scheduler/schedules' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "daily-report-schedule",
    "cronExpression": "0 0 9 * * MON-FRI",
    "zoneId": "America/New_York",
    "startWorkflowRequest": {
      "name": "daily_report_workflow",
      "version": 1,
      "correlationId": "daily-report-${scheduledTime}"
    }
  }'

List all schedules

GET /api/scheduler/schedules

Query parameters:

Parameter	Type	Required	Description
`workflowName`	string	No	Filter by workflow name

Response: 200 OK — array of WorkflowSchedule objects.

Example using cURL

# List all
curl 'http://localhost:8080/api/scheduler/schedules'

# Filter by workflow
curl 'http://localhost:8080/api/scheduler/schedules?workflowName=daily_report_workflow'

Search schedules

GET /api/scheduler/schedules/search

Query parameters:

Parameter	Type	Required	Default	Description
`workflowName`	string	No	—	Filter by workflow name
`scheduleName`	string	No	—	Filter by schedule name
`paused`	boolean	No	—	Filter by paused state
`freeText`	string	No	`*`	Free-text search
`start`	integer	No	`0`	Pagination offset
`size`	integer	No	`100`	Page size
`sort`	string	No	—	Sort fields

Response: 200 OK — SearchResult with totalHits and results array.

Example using cURL

curl 'http://localhost:8080/api/scheduler/schedules/search?workflowName=daily_report_workflow&size=10'

Get a schedule by name

GET /api/scheduler/schedules/{name}

Response: 200 OK — WorkflowSchedule object.

Example using cURL

curl 'http://localhost:8080/api/scheduler/schedules/daily-report-schedule'

Delete a schedule

DELETE /api/scheduler/schedules/{name}

Response: 204 No Content

Example using cURL

curl -X DELETE 'http://localhost:8080/api/scheduler/schedules/daily-report-schedule'

Pause a schedule

PUT /api/scheduler/schedules/{name}/pause

Query parameters:

Parameter	Type	Required	Description
`reason`	string	No	Reason for pausing

Response: 200 OK

Example using cURL

curl -X PUT 'http://localhost:8080/api/scheduler/schedules/daily-report-schedule/pause?reason=maintenance+window'

Resume a schedule

PUT /api/scheduler/schedules/{name}/resume

Response: 200 OK

Example using cURL

curl -X PUT 'http://localhost:8080/api/scheduler/schedules/daily-report-schedule/resume'

Preview next execution times

GET /api/scheduler/nextFewSchedules

Preview when a cron expression will fire next, without creating a schedule.

Query parameters:

Parameter	Type	Required	Default	Description
`cronExpression`	string	Yes	—	Cron expression to evaluate
`scheduleStartTime`	long	No	—	Window start (epoch ms)
`scheduleEndTime`	long	No	—	Window end (epoch ms)
`limit`	integer	No	`5`	Number of times to return

Response: 200 OK — array of epoch-millisecond timestamps.

Example using cURL

curl 'http://localhost:8080/api/scheduler/nextFewSchedules?cronExpression=0+0+9+*+*+MON-FRI&limit=5'

Search execution history

GET /api/scheduler/search/executions

Search past scheduled workflow executions.

Query parameters:

Parameter	Type	Required	Default	Description
`query`	string	No	—	Structured query
`freeText`	string	No	`*`	Free-text search (matches schedule name, workflow name)
`start`	integer	No	`0`	Pagination offset
`size`	integer	No	`100`	Page size
`sort`	string	No	—	Sort fields

Response: 200 OK — SearchResult with execution records:

Field	Description
`executionId`	Unique execution record ID
`scheduleName`	Parent schedule name
`scheduledTime`	Cron slot time (epoch ms)
`executionTime`	Actual dispatch time (epoch ms)
`workflowName`	Triggered workflow name
`workflowId`	Triggered workflow instance ID
`state`	`POLLED`, `EXECUTED`, or `FAILED`
`reason`	Failure reason (if `FAILED`)

Example using cURL

curl 'http://localhost:8080/api/scheduler/search/executions?freeText=daily-report-schedule&size=20'