Idempotently create or update a schedule.

Re-upserting with an unchanged spec keeps the schedule's phase (next_run is not reset); a changed spec re-anchors it. Specs are "@every:<ms>" (epoch-aligned) or a cron expression with five fields, or six fields when second-level precision is needed. A cron spec may carry a `CRON_TZ=<IANA zone>` prefix and is then evaluated on that zone's LOCAL calendar — `CRON_TZ=America/New_York 0 9 * * *`. The zone lives IN the spec string rather than in a field of its own, so changing the zone is a changed spec and re-anchors the phase like any other edit. A local time that does not exist (spring forward) is SKIPPED; one that occurs twice (fall back) fires ONCE, at the first occurrence. "@every" is always epoch-aligned UTC and REJECTS a `CRON_TZ=` prefix — an interval has no wall clock. An unknown zone is a 400 here, never a surprise at fire time. Invariant 16 applies to schedules too: the gate's periodic work is writable at runtime, not baked into a deploy. The enqueue authorizer evaluates the schedule's kind and payload before the durable definition is written, preventing a future periodic authorization bypass.

PUT /periodic/{id}

Error

A valid request URL is required to generate request examples

Headers

Idempotency-Key · string · required

Required on every mutating request. A double-clicked Retry, or a proxy retrying a POST, must not enqueue the job twice. Keys are retained long enough to cover a client retry window and the response is replayed verbatim.

Path Parameters

id · string · required

Body

application/json

kind · string · required

spec · string · required

payload · string

queue · string · default: default

partition_key · string

rate_class · string

priority · integer

max_attempts · integer

retention_ms · integer

on_missed · enum<string>

Available options: skip, run_once, backfill

backfill_limit · integer

paused · boolean

Response

200

Upserted