Skip to content
Embabel Worlds

Create or update a cron job

POST
/api/v1/cron
curl --request POST \
  --url http://localhost:11044/api/v1/cron \
  --header 'Content-Type: application/json' \
  --header 'X-Embabel-Api-Key: <X-Embabel-Api-Key>' \
  --data '{ "actionName": "example", "cron": "example", "description": "example", "name": "example", "payload": { "additionalProperty": "example" }, "zone": "example" }'

Saves the job config to the world and schedules it. If a job with the same name exists, it is replaced. The cron field uses Spring’s 6-field expression (seconds minutes hours day-of-month month day-of-week); an unparseable expression is not rejected here — the job is saved but never fires, so validate with /compile-schedule first.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”

The job to save as config/cron/<name>.yml in the caller’s world and schedule, replacing any job with the same name. cron is a Spring 6-field expression, fired in the caller’s own time zone unless zone names an IANA zone; actionName is the world action the job runs, and payload travels on the event each firing raises. An unparseable cron is saved but never fires

Media typeapplication/json

A scheduled job in the user’s world that runs a world action on a cron schedule. GET /cron lists the active ones; POST /cron takes one to create or replace.

object
actionName
required

World action the job runs when it fires. A job saved with this blank is not scheduled again when the world’s cron configs are reloaded.

string
cron
required

Spring 6-field cron expression (seconds minutes hours day-of-month month day-of-week), e.g. 0 0 9 * * *. An unparseable expression is saved but never fires.

string
description
required

What the job does, in prose; carried on the cron event the action receives

string
name
required

Job key, unique within the user’s world: saved as config/cron/.yml, and saving a job under an existing name replaces it

string
payload
required

Values handed to the action on the cron event at every firing; empty by default

object
key
additional properties
zone

IANA zone the cron expression is read in, e.g. Australia/Sydney. Null means the owning user’s own zone; an invalid zone is logged and the user’s zone used instead.

string

Example generated

{
  "actionName": "example",
  "cron": "example",
  "description": "example",
  "name": "example",
  "payload": {
    "additionalProperty": "example"
  },
  "zone": "example"
}

Responses

Section titled “Responses”

201

Section titled “201”

Job created/updated

Media type*/*
object
key
additional properties
string

400

Section titled “400”

The job config is not valid — the reason is in the message field. Note that an unparseable cron expression is NOT rejected here: validate it with /compile-schedule

Media type*/*

A refusal from the cron or handler-adoption surface: the word error and the reason

object
message
required

Why the request was refused, written to be shown. Names the job or handler where the refusal is about one

string
status
required

Always error

string
Allowed values: error