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.

Authorization

bearer

Authorizationheader · stringrequired

Session token from POST /v1/auth/login with "transport": "bearer". Browsers use the session cookie that login sets instead.

Path

namestringrequired

maxLength: 63

Body

application/json

versionintegerrequired

Version last read

format: int64minimum: 0

enabledboolean

max_attemptsinteger

format: int64minimum: 1maximum: 100

priorityinteger

format: int64minimum: 1maximum: 4

queuestring

maxLength: 100

reasonstring

Required to disable or reschedule a job

maxLength: 500

schedulestring

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

maxLength: 100

timeoutstring

Go duration such as 5m

maxLength: 20

Responses

errors: application/problem+json

200

401

Unauthorized

403

Forbidden

404

Not Found

409

Conflict

422

Unprocessable Entity

500

Internal Server Error

Match errors on the problem's code, which stays the same, not on its message.

curl -X PUT "$API_URL/ops/jobs/definitions/$NAME" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "version": 0, "enabled": false, "max_attempts": 1, "priority": 1, "queue": "string", "reason": "string", "schedule": "string", "timeout": "string" }'

body := strings.NewReader(`{ "version": 0, "enabled": false, "max_attempts": 1, "priority": 1, "queue": "string", "reason": "string", "schedule": "string", "timeout": "string" }`) req, err := http.NewRequestWithContext(ctx, http.MethodPut, apiURL + "/ops/jobs/definitions/" + name, body) if err != nil { return err } req.Header.Set("Authorization", "Bearer "+token) req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { return err } defer res.Body.Close()

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

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

{ "code": "string", "status": 422, "title": "Unprocessable Entity", "detail": "string", "errors": [ { "message": "expected length >= 1", "location": "body.name" } ], "request_id": "req_9f86d081884c7d65", "type": "string" }