Skip to main content
POST

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
agent_key
string
required

The unique routing key of the agent the schedule belongs to.

Body

application/json
​
display_name
string
required

Human-readable name of the schedule.

​
expression
string
required

6-field cron expression (sec min hour dom month dow). Seconds and minutes must be 0, day-of-month and month must be ''. Hour and weekday must each be a single integer or ''; ranges, lists, steps, and named days are rejected. Accepted shapes: hourly '0 0 * * * *', daily '0 0 9 * * *' (hour 0-23), weekly '0 0 9 * * 1' (weekday 0-6). Minimum firing cadence is 1 hour.

​
payload
object
required

Invocation payload delivered to the agent on every firing.

​
type
enum<string>
required

Schedule type. Only cron is accepted; the expression must be a 6-field cron expression firing at most once per hour.

Available options:
cron
​
agent_tag
string

Pin this schedule to a specific agent version. Omit to always use the active version.

Response

Schedule created.

​
_id
string
required

ULID identifying this schedule.

​
agent_key
string
required
​
created
string<date-time>
required
​
created_by_id
string
required

ID of the API key that created the schedule.

​
expression
string
required

6-field cron expression. Schedules stored before the cron-only restriction may also return an @every duration or an @at RFC3339 timestamp.

​
generation
integer<int64>
required

Monotonic counter bumped when the schedule's firing cadence changes. Used by the consumer to skip stale in-flight triggers.

​
is_active
boolean
required

Whether the schedule is currently firing. Legacy once schedules flip to false automatically after firing.

​
payload
object
required
​
trigger_count
integer<int64>
required

Total firings since creation or last expression/type change.

​
type
enum<string>
required

Schedule type. Only cron can be created or updated; once and interval only appear on schedules stored before that restriction.

Available options:
cron,
once,
interval
​
updated
string<date-time>
required
​
agent_tag
string

Pinned agent version. Omit to always run the agent's current active version.

​
display_name
string

Human-readable name of the schedule. Omitted for schedules created before display names were required.

​
last_triggered_at
string<date-time>

Timestamp of the most recent firing, if any.

​
updated_by_id
string

ID of the API key that last updated the schedule. Omitted until the schedule is updated.