Skip to content
Console
On this page

Jobs and cron

What a Schedule is, what a fire is not, and how one is declared and read.

A Schedule starts Runs of a Workflow on a calendar or an interval. Nothing calls it: every fire is an engine timer, so a schedule that is due fires even while nothing of yours is running.

(schedule, intended time) is the Run identity. One instant starts at most one Run, however many times a wake is delivered, so a retry or a duplicated wake cannot start the same instant's Run twice. And a fire is not a Run result: the fire is what starts the Run, and how that Run ended is the Run's own outcome.

What you set on a Schedule

FieldTypeWhat it is
calendar.kindstringThe trigger: rate, a fixed period, or cron, an expression.
calendar.everySecondsnumberThe period of a rate, 1 to 31536000 seconds.
calendar.expressionstringThe 5- or 6-field cron expression of a cron calendar.
calendar.timezonestringThe IANA time zone the calendar is read in.
overlapstringWhat a fire does while the previous Run is still running: skip, buffer_one or allow.
catchUpstringWhat a missed fire does: skip, last_only (only the most recent), or bounded by maxTicks or maxAgeSeconds.
targetobjectWhere the fire lands: an http target (an https url, a method, signed set to true), or execute, which names a jobId and its expectedRevision.
retry.maxAttemptsnumberHow many times a fire is retried.
pauseboolWhether fires are paused.

A rate's first due time is one interval after the schedule is created, so a schedule made now with a 30-second rate first fires 30 seconds from now.

How a Schedule is declared

You declare a Schedule in sylphx.toml, and each release projects it into the environment, as that environment, with its own key. A [[jobs]] row with a schedule gets one Schedule, and a [[compute.schedules]] row declares one on its own, naming the service and the path the fire is sent to. A Schedule runs in the project's production environment only; a row opts the others in with previews = true. Changing the cron or timezone replaces the Schedule in place, and removing the row retires it. The quickstart shows the whole loop.

Reading and controlling it

The one API's schedules collection is the Schedule Resource, and the calls that read and control a declared Schedule are served on api.sylphx.com. A request presents a Sylphx Access key, Authorization: Bearer sylphx_sk_…. Creating and updating a Schedule are declared in sylphx.toml, not called: the create and update methods of the collection refuse.

Base URL
https://api.sylphx.com
List
GET /v1/orgs/{org}/projects/{project}/envs/{env}/schedules
Read one
GET …/schedules/{schedule}
Pause, resume
POST …/schedules/{schedule}:pause, :resume
Delete
DELETE …/schedules/{schedule}
Scopes
workflows:read to read, workflows:write to change
Name
orgs/{org}/projects/{project}/envs/{env}/schedules/{schedule}

A declared Schedule is named <id>@<environment id>; the part before the @ is the id you declared.