Create and manage jobs

This page shows how to work with a project’s jobs. It assumes you have set up your environment.

Create a job

Create jobs through the API. Send the job’s name, schedule, and target, and any of its other fields:

curl -X POST "https://scheduler-api.digitospace.com/v1/projects/$PROJECT_ID/jobs" \
  -H "Authorization: Bearer $SCHEDULER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Refresh prices",
    "description": "Pulls the latest prices into the cache",
    "schedule": "*/10 * * * *",
    "timeZone": "Africa/Dar_es_Salaam",
    "target": {
      "url": "https://shop.example.com/tasks/prices",
      "method": "POST",
      "headers": { "Content-Type": "application/json" },
      "body": "{\"source\":\"supplier\"}"
    },
    "signing": { "enabled": true },
    "retry": { "count": 3, "minBackoffSeconds": 10 }
  }'

A job’s name must be unique in the project, ignoring case. A name already in use gets Conflict with the code job_name_taken.

Change a job

Send the whole job again with PUT. A field you leave out goes back to its default, so read the job first and change only what you need:

curl -X PUT "https://scheduler-api.digitospace.com/v1/projects/$PROJECT_ID/jobs/$JOB_ID" \
  -H "Authorization: Bearer $SCHEDULER_TOKEN" \
  -H "Content-Type: application/json" \
  -d @job.json

When the schedule or time zone changes, the next run time is worked out again from the new one.

Run a job now

Run now works whether the job is on or paused. It does not change the schedule. A job that already has a run in progress gets Conflict with the code run_in_progress.

Pause and resume a job

A paused job does not run on its schedule. Pausing cancels a scheduled run that is waiting to start or waiting to retry, and its status becomes cancelled. Resuming schedules the job again from now, so times missed while it was paused do not run.

Delete a job

Deleting a job deletes all its runs too. This cannot be undone.