Schedules

A schedule creates Work Items for a Worker agent on a cron cadence — the API equivalent of the schedule picker in the application. Use this API to create and manage schedules for your worker agents.

All paths are relative to the base URL and require an Authorization: Bearer YOUR_API_KEY header.

Schedules only exist for Worker agents. Calling these endpoints for a conversational agent returns 400 ("Schedules can only be created for worker agents"). Check an agent's mode with GET /agents/{agent_id}.

The Schedule object

PublicSchedule is returned by all endpoints here.

Field	Type	Description
id	string	Schedule ID.
agent_id	string	The Worker agent the schedule belongs to.
cron_expression	string	Standard 5-field cron expression (e.g. `0 9 * * 1-5`).
timezone	string	IANA timezone the cron expression is evaluated in.
enabled	boolean	Whether the schedule fires. Read-only — pause and resume in the application.
catch_up	boolean	On a missed occurrence (e.g. downtime), run once and advance to the next occurrence.
work_item_name	string \| null	Name given to the Work Items this schedule creates.
message	string	Message included in each created Work Item.
payload	object	Payload included in each created Work Item.
metadata	object	Free-form metadata (the application stores its picker UI state here).
last_run_at	string \| null	When the schedule last fired (`null` if never).
next_run_at	string \| null	Next planned run (`null` while paused).
created_at / updated_at	string	Timestamps.

List schedules

GET /agents/{agent_id}/schedules

Returns a PaginatedResponse whose data is a list of schedules. The endpoint takes no paging parameters — the agent's schedules are returned in one page.

curl 'https://{your-deployment-host}/api/v2/agents/{agent_id}/schedules' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Create a schedule

POST /agents/{agent_id}/schedules

Body

Field	Type	Required	Description
cron_expression	string	Yes	Standard 5-field cron expression (e.g. `0 9 * * 1-5`).
timezone	string	No	IANA timezone (e.g. `America/New_York`). Defaults to `UTC`.
catch_up	boolean	No	Run once on a missed occurrence, then advance. Defaults to `true`.
work_item_name	string	No	Name for the Work Items this schedule creates.
message	string	No	Message to include in each Work Item (max 10,000 chars).
payload	object	No	Payload to include in each Work Item.
metadata	object	No	Free-form metadata.

curl -X POST 'https://{your-deployment-host}/api/v2/agents/{agent_id}/schedules' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "cron_expression": "0 9 * * 1-5",
    "timezone": "America/New_York",
    "work_item_name": "Daily invoice batch",
    "message": "Process the overnight invoice queue",
    "payload": { "source": "email-inbox", "batch_size": 50 }
  }'

Returns the created Schedule, enabled and with next_run_at set to the first occurrence.

An invalid cron expression or timezone returns 400. Two advanced settings cap schedules: MAX_SCHEDULES_PER_AGENT (default 20) and MAX_WORK_ITEM_PAYLOAD_SIZE_IN_KB (default 100) — exceeding either returns 400.

Get a schedule

GET /agents/{agent_id}/schedules/{schedule_id}

Returns a Schedule. The schedule must belong to the given agent — otherwise 404.

Update a schedule

PUT /agents/{agent_id}/schedules/{schedule_id}

Takes the same body as create and replaces the schedule's definition with it — omitted optional fields are reset to their defaults, not left untouched. Send the full definition every time.

curl -X PUT 'https://{your-deployment-host}/api/v2/agents/{agent_id}/schedules/{schedule_id}' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "cron_expression": "30 8 * * 1-5",
    "timezone": "Europe/Helsinki",
    "work_item_name": "Daily invoice batch",
    "message": "Process the overnight invoice queue",
    "payload": { "source": "email-inbox", "batch_size": 50 }
  }'

Returns the updated Schedule with next_run_at recomputed. The enabled state is preserved: updating a paused schedule keeps it paused, and next_run_at stays unset until it's resumed in the application.

Delete a schedule

DELETE /agents/{agent_id}/schedules/{schedule_id}

Deletes the schedule. Returns 204 No Content. Work Items already created by the schedule are not affected.

Work items Data connections