Skip to main content
POST
Create event

Authorizations

Authorization
string
header
required

An API key from Settings, API Keys. A caller on this machine needs none.

Body

application/json
name
string
required
Required string length: 1 - 200
description
string
default:""
Maximum string length: 1000
color
string
default:""
Maximum string length: 32
enabled
boolean
default:true
starts_at
string

ISO 8601. Defaults to now, so a dateless every event needs no date at all

Minimum string length: 1
ends_at
string | null

When the window closes, or null for a moment rather than a window. The event reverses itself there. A suspend resumes, a spawner stop starts. So an action with no reverse cannot have one. A time-of-day at or before starts_at crosses midnight. Not until: this is when tonight's window shuts.

Minimum string length: 1
every
string | null

How often it repeats: 15m, 1h, 1d, 2w, 1 month. Null fires once. With no starts_at this is dateless. The anchor is snapped to the unit, so 1h means the top of every hour.

Maximum string length: 32
Example:

"1d"

days
enum<string>[] | null

Weekdays it may fall on, narrowing the cadence. Weekdays-only is ["mo","tu","we","th","fr"]

Available options:
mo,
tu,
we,
th,
fr,
sa,
su
monthday
integer | null

Day of the month, or -1 for its last day. The one thing starts_at cannot say, since months differ in length

Required range: -31 <= x <= 31
nth
integer | null

Which match to keep. With days ["fr"] and a monthly cadence, -1 is the last Friday of the month

Required range: -53 <= x <= 53
until
string | null

Stop repeating after this date. Null repeats forever. Not ends_at: this is when the event stops recurring at all.

action
object

The action, or use the flat shorthands below

Example:
targets
object
command
enum<string>

Shorthand for action = a command

Available options:
node.resume,
node.finish,
node.suspend,
node.reserve,
node.pool.change,
node.restart,
node.shutdown,
node.wakeup,
system.maintenance,
system.idle,
spawner.start,
spawner.stop,
run.script
pool
string

Target pool for a node.pool.change command

spawner
object

soft_id / version / type for a spawner command

Response

The created event

id
string
required
Pattern: ^[a-fA-F0-9]{24}$
Example:

"68b1f0c2a4d3e5f6a7b8c9d0"

name
string
required
description
string
default:""
required
color
string
default:""
required
enabled
boolean
default:true
required
starts_at
string
required

ISO 8601, read in the server's own zone. The only place the event's time-of-day lives

days
enum<string>[]
required

Weekdays it may fall on, narrowing the cadence. Weekdays-only is ["mo","tu","we","th","fr"]

Available options:
mo,
tu,
we,
th,
fr,
sa,
su
action
object
required
Example:
targets
object
required
last_commands
string[]
required

The commands the last fire created

history
object[]
required
created_at
number
required
updated_at
number
required
ends_at
string | null

When the window closes, or null for a moment rather than a window. The event reverses itself there. A suspend resumes, a spawner stop starts. So an action with no reverse cannot have one. A time-of-day at or before starts_at crosses midnight. Not until: this is when tonight's window shuts.

every
string | null

How often it repeats: 15m, 1h, 1d, 2w, 1 month. Null fires once. With no starts_at this is dateless. The anchor is snapped to the unit, so 1h means the top of every hour.

monthday
number | null

Day of the month, or -1 for its last day. The one thing starts_at cannot say, since months differ in length

nth
number | null

Which match to keep. With days ["fr"] and a monthly cadence, -1 is the last Friday of the month

until
string | null

Stop repeating after this date. Null repeats forever. Not ends_at: this is when the event stops recurring at all.

rule
string | null

Read-only, derived: the same recurrence as an iCalendar RRULE

open_since
number | null

The occurrence whose window is open now

last_fired_at
number | null
last_occurrence
number | null
last_dispatch
enum<string> | null

Whether the last fire got its work sent. Not whether that work succeeded

Available options:
ok,
partial,
failed,
skipped,
null
last_error
string | null
last_outcome
enum<string> | null

Read-only, rolled up from those commands: what the work actually did. Null when they have aged out of the audit trail

Available options:
ok,
partial,
failed,
running,
null
next_run_at
number | null

Computed by the server. Never derive it client-side