Skip to main content
POST
Add a cron job

Authorizations

Authorization
string
header
required

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

Headers

Idempotency-Key
string

Makes the request retry-safe. Sail remembers the answer it sent under a key, including a 400 or a 409, and replays it with Idempotent-Replayed: true for a retry that repeats the key, the method, the path, and the body. Bodies are compared byte for byte. Reusing a key for a different request returns 409, so send a corrected request under a new key. A key that is blank or only spaces is ignored, and the request runs without idempotency.

Any string of up to 255 bytes works, and characters outside ASCII count for more than one. A UUID is a good default. Keys are remembered for at least 24 hours and scoped to the API key that sent them.

A server error, or a failure to record the answer, can leave a key unsettled, and creating a Sailbox is where that matters. See Retrying safely.

Maximum string length: 255

Path Parameters

sailbox_id
string
required

Id of the Sailbox, as returned by create. It is sb_ followed by a UUID.

Body

application/json
schedule
string
required

Cron expression with five fields: minute, hour, day of month, month, and day of week. 0 9 * * 1-5 is 9:00 on weekdays.

command
string
required

Shell command each run starts. At most 16 KiB.

timezone
string

IANA time zone the schedule is read in, such as America/New_York. Defaults to UTC.

cwd
string

Working directory each run starts in.

user
string

User each run starts as: a user name or numeric uid, optionally with a group after a colon. Defaults to the image's USER, or root when the image sets none. A request made from inside the Sailbox defaults to the calling user, and only root there can set another.

env
object

Environment variables each run adds. Names must match [A-Za-z_][A-Za-z0-9_]*, and a value cannot contain a NUL character. Sail stores the values encrypted and never returns them.

timeout
integer

Seconds after which a run is killed. Without it a run has no time limit.

Required range: x >= 1

Response

The cron job was added.

id
string
required

Id of the cron job.

sailbox_id
string
required

Id of the Sailbox.

schedule
string
required

The five-field cron expression.

timezone
string
required

IANA time zone the schedule is read in.

command
string
required

Shell command each run starts.

next_run_at
string<date-time>
required

When the next run is due.

created_at
string<date-time>
required

When the job was added.

cwd
string

Working directory each run starts in. Absent when none was set.

user
string

User each run starts as. Absent when none was set.

env_names
string[]

Names of the environment variables each run adds, sorted. The values are not returned. Absent when none were set.

timeout
integer

Seconds after which a run is killed. Absent when none was set.

last_run_at
string<date-time>

When the last run started. Absent until the first run.