API reference/Ops: settings

Change a runtime setting

PUT/ops/settings/{key}

Applies to every instance within moments. Send the `version` you read; a newer version returns `setting_version_conflict`.

bearer auth

Path parameters

keystringrequired

max length 200

Request body application/json · required

reasonstring

Why; required when reason_required

max length 500

valueanyrequired

New value, as JSON of the setting's kind

versioninteger (int64)required

Version last read

≥ 0

Responses

200OKapplication/json

constraintsobject

Validation summary such as min, max, one_of, max_len

defaultanyrequired

Value declared in code

descriptionstringrequired

groupstringrequired

invalid_stored_valuebooleanrequired

The stored value fails validation, so the default applies

keystringrequired

kindstringrequired

modifiedbooleanrequired

A stored value overrides the default

reason_requiredbooleanrequired

restart_pendingbooleanrequired

restart_requiredbooleanrequired

updated_atstring (date-time)

updated_bystring

valueanyrequired

Effective value

versioninteger (int64)required

Send back when changing the setting

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/settings/value" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "string",
  "value": null,
  "version": 0
}'

req, _ := http.NewRequest("PUT", "https://api.example.com/ops/settings/value", strings.NewReader(`{
  "reason": "string",
  "value": null,
  "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/settings/value", {
  method: "PUT",
  headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "reason": "string",
    "value": null,
    "version": 0
  }),
});
const data = await res.json();

Response

{
  "constraints": {},
  "default": null,
  "description": "string",
  "group": "example",
  "invalid_stored_value": true,
  "key": "example.ping_message",
  "kind": "string",
  "modified": true,
  "reason_required": true,
  "restart_pending": true,
  "restart_required": true,
  "updated_at": "2026-09-15T12:00:00Z",
  "updated_by": "string",
  "value": null,
  "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