Settings and settings versions
Included from Basic tier
A settings document is the database-authoritative JSON settings layer of one
owner — the SystemConfiguration singleton (the global settings), a node, a
template, or a change override — versioned on every write. Two JSON:API types
share this page: settings (the live document) and settings_version (one
history row); the derived converged_settings read surface is covered at the
end. For which keys exist and how the halves of settings authority relate,
see opschain docs settings.
The v2 OpenAPI document declares these resources' schemas; the resource-field coverage gate holds this page to them.
Endpoints
| Route | Serves |
|---|---|
GET /api/settings/{id} | Show the live document. Gated on read of the owner node when the owner is a node; other owners are authenticated-only (recorded gap). |
PATCH /api/settings/{id} | Write a new version. Body attributes: data and optional version (optimistic lock); a mismatch answers 422 Version mismatch, the settings are now at version N whilst these modifications were made to version M. Please fetch the latest version of the settings and reapply the edits. |
GET /api/settings/{id}/versions | History. Default sort version desc; `filter[sorts][]=version |
GET /api/settings/{id}/versions/{version} | One history row by number (always with data); a non-integer or unknown number is a 404. |
Settings documents are reached through their owner's settings
relationship/links: every node, the system_configuration singleton
(GET /api/system_configuration → its settings relationship is the global
settings document), templates/template versions, and a change's
override_settings.
settings attributes
| Attribute | Type | Meaning / origin / null semantics |
|---|---|---|
data | object | The current stored settings, decrypted from the (possibly ActiveRecord-encrypted) column. |
version | integer | The current version number; each successful PATCH increments it. |
created_at | string | The document row's creation time (ISO8601, six fractional digits). |
Relationships: owner — links-only (links.owner is the owner node's API
URL, null for non-node owners). Links: self, current_version, versions.
settings_version attributes
| Attribute | Type | Meaning / origin / null semantics |
|---|---|---|
data | object | The settings as stored at that version. Absent (key omitted) on list rows read with exclude_data=true; always present on a show. |
version | integer | The row's version number. |
created_at | string | When the version was written. |
Unlike properties_version, a settings version serializes no
owner_type attribute. Relationships: settings (the parent document, with
its related link). Links: self (…/versions/{version}), versions,
owner (the owner URL or null).
The converged settings read surface
The stored layers are resolved on demand by three endpoints, each answering a
singleton resource of type converged_settings:
| Route | Resolves |
|---|---|
GET /api/projects/{…node path}/converged_settings | The node's effective settings: the SystemConfiguration data deep-merged with each path node's settings layer, template and template-version layers before a templated node's own. |
GET /api/changes/{id}/converged_settings | The change's settings: its frozen static-settings snapshot when one was captured, else the target node's converge deep-merged with the change's override settings. |
GET /api/steps/{id}/converged_settings | Resolves to the step's change (same document). |
Shape: id is the node code (or change id), attributes.data is the
converged document as a diff against the global settings (the
controller's default exclude_global: true), with sensitive values exposed
cipher-stacked (encrypted); meta.setting_sources attributes each key to the layer that
supplied it ("System Configuration", a node path, "Change"). The legacy
requires_approval_from key is retired: the converge strips it from every
layer and never serves it (the stored entries were never enforced; approval
policies are the successor — convert them with
opschain approval-policies convert-settings-approvers).
Recorded gaps: the deploy-authoritative half (values.yaml → the
opschain-config ConfigMap) has no Go-side source, so stored values are served
verbatim; secret-vault:// retrieval is not ported; a converge failure
answers 500 where Rails answers 422.
Related pages
opschain docs settings— the settings architecture (two authorities, resolution order, key catalog).opschain docs resources/properties— the properties twin of this document family.opschain docs cli/settings-show,opschain docs cli/settings-edit,opschain docs cli/settings-history,opschain docs cli/admin-settings.