Jobs API (REST)

Create and schedule work using a deployed job package. See Job Plugins for custom implementations and Provided Job Plugins for connector configuration.

Endpoints

Method	Path	Purpose	Rights
GET	/job	List jobs	Read or Admin
POST	/job	Create a job	Write or Admin
PUT	/job	Update a job	Write or Admin
GET	/job/{id}	Read a job by reference ULID	Read or Admin
DELETE	/job/{id}	Undeploy a job by reference ULID	Write or Admin
POST	/job/state	Read scheduler states	Read or Admin
DELETE	/job/continuation/{id}/{jobId}	Remove a continuation; reference ULID plus scheduler GUID	Write or Admin

Create a background job

Replace packageId with an installed job package's ULID. This example runs after 30 minutes:

{
  "name": "Example Background Job",
  "packageId": "01J00000000000000000000000",
  "jobType": "Background",
  "priority": "Medium",
  "configuration": null,
  "configurationLanguage": null,
  "timeZone": "Etc/UTC",
  "misfireHandling": "Relaxed",
  "backgroundJob": {
    "durationType": "AfterSpecificPeriod",
    "periodInDays": 0,
    "periodInHours": 0,
    "periodInMinutes": 30,
    "continuations": [],
    "removedContinuations": []
  }
}

Download the background request.

The request explicitly supplies priority, timeZone, and misfireHandling. For a job without configuration, send both configuration and configurationLanguage as null. For provided connectors, set configurationLanguage to Toml and put the completed TOML text in the configuration JSON string. JSON-encode that string with your client serializer.

Create a recurring job

This example uses the built-in daily schedule in UTC:

{
  "name": "Example Recurring Job",
  "packageId": "01J00000000000000000000000",
  "jobType": "Recurring",
  "priority": "Medium",
  "configuration": null,
  "configurationLanguage": null,
  "timeZone": "Etc/UTC",
  "misfireHandling": "Relaxed",
  "recurringJob": {
    "cronType": "Day",
    "cronExpression": null
  }
}

Download the recurring request.

Built-in cronType values are Minute, Hour, Day, Week, Month, and Year. Keep cronExpression null for these schedules. The current request validator rejects non-null custom cron expressions; use a built-in schedule until your deployment supports custom expressions.

Submit either request with POST /job, Content-Type: application/json, and the authentication headers.

Responses and job state

Successful creation returns HTTP 200 with { "status": true, "id": "..." }. The returned id is the job reference ULID. Job creation does not return a task identifier. A duplicate name can return 409, request validation returns 400, and a scheduling failure returns 500.

Job details expose the reference ID and scheduler IDs. Use scheduler GUIDs in the jobIds array sent to POST /job/state. The response maps scheduler IDs to states such as Scheduled, Enqueued, Processing, Succeeded, Failed, Deleted, and Awaiting. These scheduler states differ from the Tasks API lifecycle.

Next: Stopwords API