# Updates a specific system configuration setting by its key

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

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

HTML version: [Updates a specific system configuration setting by its key](https://support.gladstonesoftware.cloud/reference/configuration/updates-a-specific-system-configuration-setting-by-its-key)

## 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](retrieves-all-available-system-configuration-groups.md) and then read the settings in a group with [List settings by group](retrieves-system-configuration-settings-grouped-by-configuration-group-ids.md). 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](../../guides/authenticating-with-gladstone-apis.md).

## Path parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `configKey` | string | Yes | The setting's key, as returned by [List settings by group](retrieves-system-configuration-settings-grouped-by-configuration-group-ids.md) — 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](retrieves-all-available-system-configuration-groups.md), 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](get-all-sites-with-optional-filtering.md). 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

```bash title="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. |