# Retrieves a specific system configuration value by key and optional site ID

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

- **Success:** `200 OK`
- **Products:** Operator (`FOH`), Consumer (`CONSUMER`) (any one of these products, not all)
- **Features:** Online Bookings (`ONLINEBOOK`), Online Joining (`ONLINEJOIN`), Front of House Generic Access (`FOHGENERIC`) (any one of these features, not all)

HTML version: [Retrieves a specific system configuration value by key and optional site ID](https://support.gladstonesoftware.cloud/reference/configuration/retrieves-a-specific-system-configuration-value-by-key-and-optional-site-id)

## Overview

Reads one system configuration setting and returns its current value as a string. System
configuration is the tenant-wide switchboard behind the platform's behaviour — opening times policy,
whether a feature is on, which template to use — and each setting is addressed by a stable string
key.

**There is no endpoint that lists the keys directly, which is the first thing to solve.** Discover
them in two steps: call
[Retrieve all system configuration groups](retrieves-all-available-system-configuration-groups.md)
for the group ids, then
[Retrieve system configuration by group id](retrieves-system-configuration-settings-grouped-by-configuration-group-ids.md)
for the settings in those groups, where each entry carries its `configKey`, current value and help
text. Use this endpoint afterwards, when you already know the key and want just one value. Keys are
not documented anywhere in this portal and vary by platform version, so treat any key you hardcode
as something to re-verify.

A setting can be overridden per site. Pass `siteId` to get the value in force at that site, and omit
it for the tenant-wide value.

Values are always returned as strings — numbers, booleans and dates all arrive quoted, and you are
responsible for parsing them. Nothing in the response tells you which type to expect.

A setting changed in the back office may take a moment to appear here, and each key and site
combination catches up separately.

## Endpoint

`GET {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 to read, as its `configKey` from [Retrieve system configuration by group id](retrieves-system-configuration-settings-grouped-by-configuration-group-ids.md). Send it in exactly the case you received: the lookup itself tolerates a different case, but a mixed-case variant is refreshed separately from the exact key, so it can return a stale value after the setting changes. An unknown key returns `404`. |

## Query parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `siteId` | string | No | Return the value as overridden for one site rather than the tenant-wide value. Case-insensitive — it is upper-cased before use. Omit it to read the tenant-wide value. **A site id that does not exist is silently ignored**, and you get the tenant-wide value with a `200` rather than a `404`, so a typo here shows up as a plausible-looking wrong answer. Where the site has no override for the key, the tenant-wide value is returned. |

## Sample request

```bash title="cURL"
curl -X GET '{base_url}/api/configuration/system/{configKey}' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'X-Use-SSO: true'
```

## Response fields

| Field | Type | Description |
|-------|------|-------------|
| `value` | string | The setting's value, always as a string whatever the underlying type — parse it yourself, and expect `"true"`, `"0"` or a formatted date rather than a JSON boolean, number or date. It is the site override where `siteId` was supplied and an override exists, and the tenant-wide value otherwise; the response does not say which of the two you got. May be an empty string for a setting that exists but has never been given a value. |

## Sample response

```json title="200 OK"
{
  "value": "string"
}
```

## Errors

| Status | Meaning | When |
|--------|---------|------|
| `403` | Forbidden | Either the setting is marked as staff-only and your token identifies a logged-in member, or the setting is gated behind a module your token does not carry. The body is **empty** in both cases — the explanation is only in Gladstone's logs — so you cannot tell the two apart from the response. Note it means the key does exist; a key you cannot see is a `403`, not a `404`. |
| `404` | Not found | No setting exists with that key. The body is the plain string `Unable to find a configurations with the configurations key of {configKey}`. An unknown `siteId` never causes this — it is ignored. |
| `500` | Internal server error | Any unexpected server-side failure, with an empty body. |