Updates multiple system configuration settings within a specific group

PUT /api/configuration/system/group/{groupId}

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

Overview

Changes several platform settings at once, all of which must belong to one configuration group. The body is a JSON array, not an object.

Settings are pre-defined; this endpoint cannot create one. Every key you send must already exist inside the group named in the URL, or the whole call fails with 404. Discover the groups with List configuration groups and the keys within a group with List settings by group. Unlike the single-setting endpoint, key matching here is case-sensitive — send keys exactly as that listing returns them.

Every entry replaces the setting it names. value, description and helpText are overwritten from your body, so omitting description or helpText clears the text that documented the setting. Settings in the group that you do not mention are left completely alone, so you only need to send the ones you are changing.

overrides behaves differently here than on the single-setting endpoint. On this endpoint:

omit overrides and the setting's existing per-site overrides are left untouched;
send [] and every override on that setting is deleted;
send entries and they are merged — listed sites are updated or added, and any site not listed loses its override.

Getting this backwards is the easiest way to wipe per-site configuration, so be deliberate about which of the three you send.

The update is atomic, but validation is not exhaustive. Everything is saved in one operation, so a failure applies nothing. However site ids in overrides are not checked against real sites on this endpoint — an id that does not exist fails with 500. A successful call returns 204 No Content, and every site reads the new values from then on.

Endpoint

PUT {base_url}/api/configuration/system/group/{groupId}

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

Path parameters

Name	Type	Required	Description
`groupId`	integer (int32)	Yes	The configuration group whose settings you are changing, as returned by List configuration groups. Every entry in the body must repeat this value in its own `groupId`. A group that does not exist fails with `404`.

Request body

Field	Type	Required	Description
`[].groupId`	integer (int32)	Yes	Must equal the `groupId` in the URL on every entry — a mismatch anywhere fails the whole call with `At least one group ID in the request does not match the group ID in the route`. It does not move the setting between groups; it only guards against sending a body assembled for a different group.
`[].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. Resend the current value.
`[].configKey`	string	Yes	The key of the setting this entry updates — for example `Cultures_AllowedLanguages`. It must already exist and belong to the group in the URL, matched case-sensitively; anything else fails the whole call with `404`. The same key may appear only once in the array: repeating it fails with `duplicate configKeys are not allowed in the request`.
`[].value`	string	Yes	The setting's new global value, used by every site with 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 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	Per-site values that take precedence over `value` for this setting. Three distinct meanings: absent leaves the stored overrides untouched, `[]` deletes them all, and a non-empty array makes the stored set match what you sent — listed sites are updated or created, unlisted sites lose their override. Only usable on settings whose own `allowOverrides` flag is set; sending entries for one that forbids overriding fails with `This config key: ["{key}"] does not allow site overrides`, naming every offending key. Sending `[]` is always allowed, including on settings that no longer permit overrides, so that historic overrides can be cleaned up.
`[].overrides[].siteId`	string	Yes	The site this override applies to, as returned in `id` by List sites. Must not be null or empty — that fails with `Found a null or empty site Id for the override…`. Unlike the single-setting endpoint, the id is not checked against real sites here, so a typo passes validation and then fails with `500`.
`[].overrides[].value`	string	Yes	The value this site uses instead of the global `value`. Must not be null or empty on this endpoint — that fails with `Found a null or empty value for the override…`, which differs from the single-setting endpoint where an empty override value is accepted. To remove a site's override, leave the site out of the array instead.
`[].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. Resend the value you read back.

Sample request

cURL

curl -X PUT '{base_url}/api/configuration/system/group/{groupId}' \
  -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	An entry's `groupId` differs from the `groupId` in the URL — `At least one group ID in the request does not match the group ID in the route`. Checked before anything else, so nothing is applied.
`400`	Bad request	The same `configKey` appears more than once — `duplicate configKeys are not allowed in the request`.
`400`	Bad request	You sent non-empty `overrides` for one or more settings that do not permit them — `This config keys: ["{key1}","{key2}"] does not allow site overrides`. The message lists every offending key.
`400`	Bad request	An override has a null or empty `siteId` or `value` — `Found a null or empty site Id for the override…` or `Found a null or empty value for the override…`, each quoting the offending entry.
`400`	Bad request	A `Cultures_AllowedLanguages` entry contains a language code the platform does not know — `One of the languages in the request is not valid.`
`400`	Bad request	A `[].value` is null or absent, or a `[].description` exceeds 100 characters. The body is a validation error object keyed by field name.
`404`	Not found	The `groupId` does not exist — `Group ID {groupId} not found`.
`404`	Not found	At least one `configKey` is not a setting in that group, or its casing does not match — `At least one config key in the configurationInRequest for Group ID {groupId} was not found`. The message does not say which key.
`500`	Internal server error	The body is an empty array, or an `overrides[].siteId` does not match a real site — neither is validated up front. Nothing is partially applied.

This page as markdown · All pages · llms.txt