API reference/Ops: job definitions

Change a job's configuration

PUT/ops/jobs/definitions/{name}

Send only the fields to change. Applies to every instance within moments. Disabling or rescheduling requires a reason.

bearer auth

Path parameters

namestringrequired

max length 63

Request body application/json · required

enabledboolean

max_attemptsinteger (int64)

≥ 1 · ≤ 100

priorityinteger (int64)

≥ 1 · ≤ 4

queuestring

max length 100

reasonstring

Required to disable or reschedule a job

max length 500

schedulestring

5-field cron in UTC, @every duration, or empty for on-demand

max length 100

timeoutstring

Go duration such as 5m

max length 20

versioninteger (int64)required

Version last read

≥ 0

Responses

200OKapplication/json

configobjectrequired

enabledbooleanrequired

max_attemptsinteger (int64)required

priorityinteger (int64)required

queuestringrequired

schedulestringrequired

5-field cron in UTC, @every duration, or empty for on-demand

timeoutstringrequired

Go duration

defaultsobjectrequired

enabledbooleanrequired

max_attemptsinteger (int64)required

priorityinteger (int64)required

queuestringrequired

schedulestringrequired

5-field cron in UTC, @every duration, or empty for on-demand

timeoutstringrequired

Go duration

descriptionstringrequired

invalid_overridebooleanrequired

The stored override fails validation, so the defaults apply

last_runobject

actor_idstring

actor_kindstring

attemptinteger (int64)required

attempted_atstring (date-time)

created_atstring (date-time)required

errorsarray of object

finalized_atstring (date-time)

idinteger (int64)required

kindstringrequired

max_attemptsinteger (int64)required

priorityinteger (int64)required

queuestringrequired

request_idstring

scheduled_atstring (date-time)required

statestringrequired

modifiedbooleanrequired

namestringrequired

next_run_atstring (date-time)

Approximate next scheduled run

updated_atstring (date-time)

updated_bystring

versioninteger (int64)required

Send back when changing the definition

401Unauthorizedapplication/problem+json

codestringrequired

Stable machine-readable error code

detailstring

Human-readable explanation

errorsarray of object

Field-level validation errors

request_idstring

Correlates with server logs and traces

statusinteger (int64)required

HTTP status code

titlestringrequired

Short summary of the problem type

typestring

URI identifying the problem type

403Forbiddenapplication/problem+json

codestringrequired

Stable machine-readable error code

detailstring

Human-readable explanation

errorsarray of object

Field-level validation errors

request_idstring

Correlates with server logs and traces

statusinteger (int64)required

HTTP status code

titlestringrequired

Short summary of the problem type

typestring

URI identifying the problem type

404Not Foundapplication/problem+json

codestringrequired

Stable machine-readable error code

detailstring

Human-readable explanation

errorsarray of object

Field-level validation errors

request_idstring

Correlates with server logs and traces

statusinteger (int64)required

HTTP status code

titlestringrequired

Short summary of the problem type

typestring

URI identifying the problem type

409Conflictapplication/problem+json

codestringrequired

Stable machine-readable error code

detailstring

Human-readable explanation

errorsarray of object

Field-level validation errors

request_idstring

Correlates with server logs and traces

statusinteger (int64)required

HTTP status code

titlestringrequired

Short summary of the problem type

typestring

URI identifying the problem type

422Unprocessable Entityapplication/problem+json

codestringrequired

Stable machine-readable error code

detailstring

Human-readable explanation

errorsarray of object

Field-level validation errors

request_idstring

Correlates with server logs and traces

statusinteger (int64)required

HTTP status code

titlestringrequired

Short summary of the problem type

typestring

URI identifying the problem type

500Internal Server Errorapplication/problem+json

codestringrequired

Stable machine-readable error code

detailstring

Human-readable explanation

errorsarray of object

Field-level validation errors

request_idstring

Correlates with server logs and traces

statusinteger (int64)required

HTTP status code

titlestringrequired

Short summary of the problem type

typestring

URI identifying the problem type

Was this page useful?

v0.5

Request

curl -X PUT "https://api.example.com/ops/jobs/definitions/value" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "enabled": true,
  "max_attempts": 1,
  "priority": 1,
  "queue": "string",
  "reason": "string",
  "schedule": "string",
  "timeout": "string",
  "version": 0
}'

req, _ := http.NewRequest("PUT", "https://api.example.com/ops/jobs/definitions/value", strings.NewReader(`{
  "enabled": true,
  "max_attempts": 1,
  "priority": 1,
  "queue": "string",
  "reason": "string",
  "schedule": "string",
  "timeout": "string",
  "version": 0
}`))
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
	return err
}
defer resp.Body.Close()

const res = await fetch("https://api.example.com/ops/jobs/definitions/value", {
  method: "PUT",
  headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "enabled": true,
    "max_attempts": 1,
    "priority": 1,
    "queue": "string",
    "reason": "string",
    "schedule": "string",
    "timeout": "string",
    "version": 0
  }),
});
const data = await res.json();

Response

{
  "config": {
    "enabled": true,
    "max_attempts": 5,
    "priority": 1,
    "queue": "default",
    "schedule": "0 3 * * *",
    "timeout": "5m0s"
  },
  "defaults": {
    "enabled": true,
    "max_attempts": 5,
    "priority": 1,
    "queue": "default",
    "schedule": "0 3 * * *",
    "timeout": "5m0s"
  },
  "description": "string",
  "invalid_override": true,
  "last_run": {
    "actor_id": "string",
    "actor_kind": "string",
    "attempt": 1,
    "attempted_at": "2026-09-15T12:00:00Z",
    "created_at": "2026-09-15T12:00:00Z",
    "errors": [
      {
        "at": "2026-09-15T12:00:00Z",
        "attempt": 1,
        "message": "string"
      }
    ],
    "finalized_at": "2026-09-15T12:00:00Z",
    "id": 1,
    "kind": "heartbeat",
    "max_attempts": 1,
    "priority": 1,
    "queue": "string",
    "request_id": "string",
    "scheduled_at": "2026-09-15T12:00:00Z",
    "state": "completed"
  },
  "modified": true,
  "name": "heartbeat",
  "next_run_at": "2026-09-15T12:00:00Z",
  "updated_at": "2026-09-15T12:00:00Z",
  "updated_by": "string",
  "version": 1
}

{
  "code": "project_name_taken",
  "detail": "project name is already taken",
  "errors": [
    {
      "location": "body.name",
      "message": "expected length >= 1"
    }
  ],
  "request_id": "req_9f86d081884c7d65",
  "status": 409,
  "title": "Conflict",
  "type": "string"
}

{
  "code": "project_name_taken",
  "detail": "project name is already taken",
  "errors": [
    {
      "location": "body.name",
      "message": "expected length >= 1"
    }
  ],
  "request_id": "req_9f86d081884c7d65",
  "status": 409,
  "title": "Conflict",
  "type": "string"
}

{
  "code": "project_name_taken",
  "detail": "project name is already taken",
  "errors": [
    {
      "location": "body.name",
      "message": "expected length >= 1"
    }
  ],
  "request_id": "req_9f86d081884c7d65",
  "status": 409,
  "title": "Conflict",
  "type": "string"
}

{
  "code": "project_name_taken",
  "detail": "project name is already taken",
  "errors": [
    {
      "location": "body.name",
      "message": "expected length >= 1"
    }
  ],
  "request_id": "req_9f86d081884c7d65",
  "status": 409,
  "title": "Conflict",
  "type": "string"
}

{
  "code": "project_name_taken",
  "detail": "project name is already taken",
  "errors": [
    {
      "location": "body.name",
      "message": "expected length >= 1"
    }
  ],
  "request_id": "req_9f86d081884c7d65",
  "status": 409,
  "title": "Conflict",
  "type": "string"
}

{
  "code": "project_name_taken",
  "detail": "project name is already taken",
  "errors": [
    {
      "location": "body.name",
      "message": "expected length >= 1"
    }
  ],
  "request_id": "req_9f86d081884c7d65",
  "status": 409,
  "title": "Conflict",
  "type": "string"
}

Base URL: https://api.example.com
Auth: bearer