Settings

The organization's settings and its switches (feature settings).

GET/v1/settings/switches/{key}

Set a switch at a scope

setSwitchsettings:writewrite: 120/min per keySince 2026-10-01

Sets the value for the scope and everything below it that doesn't set its own, and with locked: true locks it for the levels below. scope is organization (the default), subject or unit, with scopeId naming the subject (sub_…) or unit (unit_…). A value of the wrong kind is 400 invalid_request. A switch a level above has locked, or one zero data retention holds, is 409 conflict (details.reason: locked or held). A switch whose plan feature the plan doesn't include can only be switched off (403 upgrade_required, naming the plan). The key acts as an admin of the organization: a switch only an owner changes, or one only Zentiq switches on, has canChange: false and is refused (403 forbidden). consent.mode also needs people:write. Recorded as setting.changed.

Path parameters

keystringrequired
The switch's key, like transcripts.leader_view.

Query parameters

scope"organization" | "subject" | "unit"
Default organization.
scopeIdstring
The subject (sub_…) or unit (unit_…); required with scope=subject or scope=unit, ignored for the organization.

Body

valueboolean | string | numberrequired
On or off, one of options, or a number between min and max, by type.
lockedboolean
Lock it for the levels below (only a lockable switch; default false, which also unlocks it).

Returns

200 The switch, as it now applies at the scope. data is Switch.

Fields of data

keystringrequired
groupstringrequired
labelstringrequired
descriptionstringrequired
type"boolean" | "enum" | "number"required
optionsobject[] | nullrequired
The values an enum switch takes.
minnumber | nullrequired
maxnumber | nullrequired
valueboolean | string | numberrequired
The value that applies at this scope, on the organization's plan.
recommendedboolean | string | numberrequired
The recommended value for the type of organization (what applies when nothing is set).
sourceSwitchSourcerequired
Where the value comes from.
lockedbooleanrequired
Locked here or at a level above: levels below can't change it.
lockedBySwitchSource | nullrequired
The level that locked it.
lockablebooleanrequired
Whether a level may lock it for the levels below.
heldBy"zero_data_retention" | nullrequired
Held by zero data retention: it keeps the held value everywhere and nobody can change it while zero data retention is on.
planFeaturestring | nullrequired
The plan feature this switch needs, when the plan doesn't include it: it stays at its default (or off), and can only be cleared or switched off.
canChangebooleanrequired
Whether this key may set it at this scope.
canLockbooleanrequired
Whether this key may lock it at this scope.
overridesSwitchOverride[]
At the organization scope only: the values set for single subjects and units.

Errors

invalid_request unauthorized forbidden upgrade_required not_found conflict rate_limited server_error

Events

setting.changed

Request

curl -X PUT "https://app.zentiqai.com/v1/settings/switches/KEY" \
  -H "Authorization: Bearer $ZENTIQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "value": true
}'

import { Zentiq } from "@zentiq/node";

const zentiq = new Zentiq({ apiKey: process.env.ZENTIQ_API_KEY });
const result = await zentiq.setSwitch("KEY", {
  value: true,
});

import os
from zentiq import Zentiq

zentiq = Zentiq(api_key=os.environ["ZENTIQ_API_KEY"])
result = zentiq.set_switch("KEY", {
    "value": True,
})

Response

200 · JSON

{
  "data": {
    "key": "transcripts.leader_view",
    "group": "…",
    "label": "…",
    "description": "…",
    "type": "boolean",
    "options": [
      {
        "value": "…",
        "label": "…"
      }
    ]
  },
  "error": null,
  "requestId": "req_4f1c2e9a7b3d5e6f7a8b9c0d"
}

DELETE/v1/settings/switches/{key}

Clear a switch at a scope

clearSwitchsettings:writewrite: 120/min per keySince 2026-10-01

Removes the value set at the scope (and its lock), so the value of the level above, or the recommended default, applies again. Always allowed on the plan; a level above's lock still applies (409 conflict). scope is organization (the default), subject or unit, with scopeId naming the subject (sub_…) or unit (unit_…). The key acts as an admin of the organization: a switch only an owner changes, or one only Zentiq switches on, has canChange: false and is refused (403 forbidden). consent.mode also needs people:write. Recorded as setting.changed.

Path parameters

keystringrequired
The switch's key, like transcripts.leader_view.

Query parameters

scope"organization" | "subject" | "unit"
Default organization.
scopeIdstring
The subject (sub_…) or unit (unit_…); required with scope=subject or scope=unit, ignored for the organization.

Returns

200 The switch, as it now applies at the scope. data is Switch.

Fields of data

keystringrequired
groupstringrequired
labelstringrequired
descriptionstringrequired
type"boolean" | "enum" | "number"required
optionsobject[] | nullrequired
The values an enum switch takes.
minnumber | nullrequired
maxnumber | nullrequired
valueboolean | string | numberrequired
The value that applies at this scope, on the organization's plan.
recommendedboolean | string | numberrequired
The recommended value for the type of organization (what applies when nothing is set).
sourceSwitchSourcerequired
Where the value comes from.
lockedbooleanrequired
Locked here or at a level above: levels below can't change it.
lockedBySwitchSource | nullrequired
The level that locked it.
lockablebooleanrequired
Whether a level may lock it for the levels below.
heldBy"zero_data_retention" | nullrequired
Held by zero data retention: it keeps the held value everywhere and nobody can change it while zero data retention is on.
planFeaturestring | nullrequired
The plan feature this switch needs, when the plan doesn't include it: it stays at its default (or off), and can only be cleared or switched off.
canChangebooleanrequired
Whether this key may set it at this scope.
canLockbooleanrequired
Whether this key may lock it at this scope.
overridesSwitchOverride[]
At the organization scope only: the values set for single subjects and units.

Errors

invalid_request unauthorized forbidden upgrade_required not_found conflict rate_limited server_error

Events

setting.changed

Request

curl -X DELETE "https://app.zentiqai.com/v1/settings/switches/KEY" \
  -H "Authorization: Bearer $ZENTIQ_API_KEY"

import { Zentiq } from "@zentiq/node";

const zentiq = new Zentiq({ apiKey: process.env.ZENTIQ_API_KEY });
const result = await zentiq.clearSwitch("KEY");

import os
from zentiq import Zentiq

zentiq = Zentiq(api_key=os.environ["ZENTIQ_API_KEY"])
result = zentiq.clear_switch("KEY")

Response

200 · JSON

{
  "data": {
    "key": "transcripts.leader_view",
    "group": "…",
    "label": "…",
    "description": "…",
    "type": "boolean",
    "options": [
      {
        "value": "…",
        "label": "…"
      }
    ]
  },
  "error": null,
  "requestId": "req_4f1c2e9a7b3d5e6f7a8b9c0d"
}

GET/v1/settings/organization

Get the organization's settings

getOrganizationSettingssettings:readread: 600/min per keySince 2026-10-01

Its name, type, brand (logo and colors), country, time zone, privacy notice and safeguarding contacts, as Settings shows them. The safeguarding contacts are email addresses: they are null unless the key also holds safety:read (given only by an owner or admin in the console).

Returns

200 The organization's settings. data is OrganizationSettings.

Fields of data

idstringrequired
Organisation id (org_…).
pattern `^org_.*`
namestringrequired
The organization's name, as its people see it.
type"school" | "company" | "tutoring" | "individual" | "family" | "other"required
The type of organization: its words (learners or trainees, classes or teams) and its recommended switches.
apiDisplayNamestring | nullrequired
The name the API shows for the organization (GET /me); null: its name.
logoUrlstring | nullrequired
primaryColorstring | nullrequired
A 6-digit hex color, like #0d9488.
secondaryColorstring | nullrequired
countrystring | nullrequired
Two-letter country code: the emergency and help lines its avatars give, and the age under which a parent must consent.
timeZonestring | nullrequired
IANA time zone, for dates in alerts.
safeguardingContactsstring[] | nullrequired
Email addresses told at once when someone may not be safe (at most 10). Null unless the key also holds safety:read.
privacyNoticeUrlstring | nullrequired
The organization's own privacy notice, linked where people start a conversation.
createdAtstring (date-time)required
ISO 8601 UTC timestamp.

Errors

invalid_request unauthorized forbidden upgrade_required rate_limited server_error

Request

curl "https://app.zentiqai.com/v1/settings/organization" \
  -H "Authorization: Bearer $ZENTIQ_API_KEY"

import { Zentiq } from "@zentiq/node";

const zentiq = new Zentiq({ apiKey: process.env.ZENTIQ_API_KEY });
const result = await zentiq.getOrganizationSettings();

import os
from zentiq import Zentiq

zentiq = Zentiq(api_key=os.environ["ZENTIQ_API_KEY"])
result = zentiq.get_organization_settings()

Response

200 · JSON

{
  "data": {
    "id": "org_cmfq2b7x10000abcd1234",
    "name": "Zoe",
    "type": "company",
    "apiDisplayName": "…",
    "logoUrl": "https://www.example.com",
    "primaryColor": "#0d9488"
  },
  "error": null,
  "requestId": "req_4f1c2e9a7b3d5e6f7a8b9c0d"
}

PATCH/v1/settings/organization

Change the organization's settings

updateOrganizationSettingssettings:writewrite: 120/min per keySince 2026-10-01

Only the fields sent change, with the console's checks (400 invalid_request naming the field). A change to the country, time zone, safeguarding contacts or privacy notice is recorded as setting.changed in the event log (for the safeguarding contacts, how many, never the addresses). The safeguarding settings (safeguardingContacts, country, timeZone, privacyNoticeUrl) change only with safety:write as well (403 forbidden naming the field otherwise), even on a full-access key. Only an owner changes the type of organization, in the console: a key acts as an admin (403 forbidden).

Body

namestring
1-80 characters, on one line.
apiDisplayNamestring | null
Up to 80 characters; empty or null clears it.
logoUrlstring | null
A web address starting with http(s)://; empty or null clears it.
primaryColorstring
A 6-digit hex color, like #0d9488.
secondaryColorstring
A 6-digit hex color.
countrystring | null
Two-letter country code (UK is read as GB); null clears it.
timeZonestring | null
IANA time zone (Europe/Paris); null clears it.
safeguardingContactsstring[]
Replaces the list: at most 10 email addresses. [] clears it.
privacyNoticeUrlstring | null
A web address starting with https://; null clears it.
type"school" | "company" | "tutoring" | "individual" | "family" | "other"
Only an owner changes the type of organization, in the console (403 forbidden for every key).

Returns

200 The organization's settings. data is OrganizationSettings.

Fields of data

idstringrequired
Organisation id (org_…).
pattern `^org_.*`
namestringrequired
The organization's name, as its people see it.
type"school" | "company" | "tutoring" | "individual" | "family" | "other"required
The type of organization: its words (learners or trainees, classes or teams) and its recommended switches.
apiDisplayNamestring | nullrequired
The name the API shows for the organization (GET /me); null: its name.
logoUrlstring | nullrequired
primaryColorstring | nullrequired
A 6-digit hex color, like #0d9488.
secondaryColorstring | nullrequired
countrystring | nullrequired
Two-letter country code: the emergency and help lines its avatars give, and the age under which a parent must consent.
timeZonestring | nullrequired
IANA time zone, for dates in alerts.
safeguardingContactsstring[] | nullrequired
Email addresses told at once when someone may not be safe (at most 10). Null unless the key also holds safety:read.
privacyNoticeUrlstring | nullrequired
The organization's own privacy notice, linked where people start a conversation.
createdAtstring (date-time)required
ISO 8601 UTC timestamp.

Errors

invalid_request unauthorized forbidden upgrade_required rate_limited server_error

Events

setting.changed

Request

curl -X PATCH "https://app.zentiqai.com/v1/settings/organization" \
  -H "Authorization: Bearer $ZENTIQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

import { Zentiq } from "@zentiq/node";

const zentiq = new Zentiq({ apiKey: process.env.ZENTIQ_API_KEY });
const result = await zentiq.updateOrganizationSettings({});

import os
from zentiq import Zentiq

zentiq = Zentiq(api_key=os.environ["ZENTIQ_API_KEY"])
result = zentiq.update_organization_settings({})

Response

200 · JSON

{
  "data": {
    "id": "org_cmfq2b7x10000abcd1234",
    "name": "Zoe",
    "type": "company",
    "apiDisplayName": "…",
    "logoUrl": "https://www.example.com",
    "primaryColor": "#0d9488"
  },
  "error": null,
  "requestId": "req_4f1c2e9a7b3d5e6f7a8b9c0d"
}

GET/v1/settings/switches

List the switches at a scope

listSwitchessettings:readread: 600/min per keySince 2026-10-01

Each switch with the value that applies at the scope on the organization's plan, where that value comes from (the recommended default, the organization, a subject or a unit), whether it is locked and by which level, whether the plan holds it back (planFeature), and whether this key may change or lock it there. At the organization scope each switch also lists the values set for single subjects and units. scope is organization (the default), subject or unit, with scopeId naming the subject (sub_…) or unit (unit_…). Only the switches Settings > Features offers at that scope are here: those that can be set there, and a switch that no longer shows in settings only while it is changed at that scope (so it can be put back). Anything else is 404 not_found.

Query parameters

scope"organization" | "subject" | "unit"
Default organization.
scopeIdstring
The subject (sub_…) or unit (unit_…); required with scope=subject or scope=unit, ignored for the organization.

Returns

200 The switches. data is SwitchList.

Fields of data

scope"organization" | "subject" | "unit"required
Where a switch is read or set: the whole organization, one subject (sub_…) or one unit (unit_…).
scopeIdstringrequired
The organization (org_…), subject (sub_…) or unit (unit_…).
switchesSwitch[]required

Errors

invalid_request unauthorized forbidden upgrade_required not_found rate_limited server_error

Request

curl "https://app.zentiqai.com/v1/settings/switches" \
  -H "Authorization: Bearer $ZENTIQ_API_KEY"

import { Zentiq } from "@zentiq/node";

const zentiq = new Zentiq({ apiKey: process.env.ZENTIQ_API_KEY });
const result = await zentiq.listSwitches();

import os
from zentiq import Zentiq

zentiq = Zentiq(api_key=os.environ["ZENTIQ_API_KEY"])
result = zentiq.list_switches()

Response

200 · JSON

{
  "data": {
    "scope": "organization",
    "scopeId": "org_123",
    "switches": [
      {
        "key": "transcripts.leader_view",
        "group": "…",
        "label": "…",
        "description": "…",
        "type": "boolean",
        "options": [
          {
            "value": null,
            "label": null
          }
        ]
      }
    ]
  },
  "error": null,
  "requestId": "req_4f1c2e9a7b3d5e6f7a8b9c0d"
}

Get a switch at a scope

Path parameters

Query parameters

Returns

Errors

Request

Response

Set a switch at a scope

Path parameters

Query parameters

Body

Returns

Errors

Events

Request

Response

Clear a switch at a scope

Path parameters

Query parameters

Returns

Errors

Events

Request

Response

Get the organization's settings

Returns

Errors

Request

Response

Change the organization's settings

Body

Returns

Errors

Events

Request

Response

List the switches at a scope

Query parameters

Returns

Errors

Request

Response