Updates a specific system configuration setting by its key

PUT /api/configuration/system/{configKey}

Products: Operator (FOH)
Features: Front of House Generic Access (FOHGENERIC)

Overview

Changes one platform setting, identified by its configuration key, together with any per-site overrides of it.

Settings are pre-defined; this endpoint cannot create one. Every key that exists is shipped with the platform, so a key you invent is rejected with 404 and The config key {configKey} could not be found — nothing is created. To discover the keys available to you, list the setting groups with List configuration groups and then read the settings in a group with List settings by group. That listing is also where you find each setting's current value, its help text, and whether it accepts per-site overrides. Key matching is case-insensitive.

This is a full replacement, not a partial update. value, description and helpText are written from your body on every call, so omitting description or helpText clears the text that documented the setting. overrides is worse: omitting it, or sending an empty array, deletes every per-site override the setting has, quietly returning all sites to the global value. Read the setting first and send its current state back with your change applied.

Values are barely validated. Almost every setting stores its value as free text with no type or range checking, so "maybe" in a setting the platform reads as a boolean is accepted here and only misbehaves later, wherever the setting is consumed. The one exception in the shipped configuration is Cultures_AllowedLanguages, whose value and overrides must be comma-separated language codes the platform knows. Treat the setting's help text as the specification for what its value should look like.

A successful update returns 204 No Content, and every site reads the new value from then on.

Endpoint

PUT {base_url}/api/configuration/system/{configKey}

{base_url} is the environment URL issued to your integration. See Authenticating with Gladstone APIs.

Path parameters

Name	Type	Required	Description
`configKey`	string	Yes	The setting's key, as returned by List settings by group — for example `Cultures_AllowedLanguages` or `Consent_AgeOfConsent`. Matched case-insensitively. A key that does not already exist fails with `404`; this endpoint never creates a setting.

Request body

Field	Type	Required	Description
`groupId`	integer (int32)	Yes	Required by validation but ignored — a setting cannot be moved between groups here, and whatever you send has no effect. Send the setting's current group id, from List configuration groups, to keep the request honest.
`description`	string	No	The setting's short label, as shown to whoever administers it. Maximum 100 characters, or the call fails with `Description cannot exceed 100 characters.` Always overwritten, so omitting it or sending null clears the stored label, leaving the setting unlabelled in the administration UI. Resend the current value.
`configKey`	string	Yes	Required by validation but ignored — the key is taken from the URL, and this field cannot rename a setting. Send the same value as the path parameter to avoid confusion.
`value`	string	Yes	The setting's new global value, used by every site that has no override. Always a string on the wire, whatever the setting represents — numbers as `"16"`, booleans as `"0"` or `"1"` following the convention the setting already uses, lists as comma-separated with no spaces. An empty string is explicitly allowed and is how most settings are cleared, but the field must be present: null or absent fails validation. Nothing checks the value against the setting's meaning, except for `Cultures_AllowedLanguages`.
`overrides`	array of object	No	The complete set of per-site values that take precedence over `value`. The list is absolute: whatever you send replaces the stored overrides, so omitting the field or sending `[]` removes every override. Only usable on settings that permit overriding — the setting's own `allowOverrides` flag controls this and cannot be changed through the API; sending overrides for a setting that forbids them fails with `This config key: {configKey} does not allow site overrides`. Send at most one entry per site; duplicates are not detected.
`overrides[].siteId`	string	Yes	The site this override applies to, as returned in `id` by List sites. Every id must exist or the whole call fails with `One or more sites supplied were invalid`, which does not say which one. Required in practice — an omitted or null id will not match a site and fails that check.
`overrides[].value`	string	Yes	The value this site uses instead of the global `value`. Follows the same free-text rules: no type checking, and an empty string is a legitimate value meaning "empty at this site" rather than "no override". To stop overriding a site, leave it out of the array rather than sending an empty value.
`helpText`	string	No	The longer explanation of what the setting does and what its value should look like, shown alongside it in the administration UI. Always overwritten, so omitting it or sending null erases the platform's own documentation of the setting. This is the field most easily lost on this endpoint: resend the value you read back.

Sample request

cURL

curl -X PUT '{base_url}/api/configuration/system/{configKey}' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'X-Use-SSO: true' \
  -H 'Content-Type: application/json' \
  -d '{
  "groupId": 12345,
  "description": "string",
  "configKey": "string",
  "value": "string",
  "overrides": [
    {
      "siteId": "string",
      "value": "string"
    }
  ],
  "helpText": "string"
}'

Errors

Status	Meaning	When
`400`	Bad request	`groupId`, `configKey` or `value` is absent, or `description` is over 100 characters. The body is a validation error object keyed by field name; note that `value` may be an empty string but not null.
`400`	Bad request	You sent `overrides` for a setting that does not permit them — `This config key: {configKey} does not allow site overrides`.
`400`	Bad request	An `overrides[].siteId` does not match an existing site — `One or more sites supplied were invalid`. The message does not identify which entry failed, and nothing is written.
`400`	Bad request	The key is `Cultures_AllowedLanguages` and `value` or any override value contains a language code the platform does not know — `One of the languages in the request is not valid.` Codes are compared case-insensitively; separate multiple codes with commas and no spaces.
`404`	Not found	No setting has that key — `The config key {configKey} could not be found`. Settings cannot be created through this endpoint.
`500`	Internal server error	An unexpected server-side failure, including sending the same site more than once in `overrides`. The response body is empty.

This page as markdown · All pages · llms.txt