Settings and switches

Everything you set in the console's Settings can be read and changed through the API, with the same rules: the organization's profile, brand and safety details, and its switches (the feature settings under Settings › Features). A change made with a key is recorded as made by that key, exactly as a change made in the console is recorded with the person who made it.

Reading needs settings:read. Changing needs settings:write.

The organization's settings#

GET /v1/settings/organization returns the organization's name, its type, its brand (logo and two colors), its country, its time zone, the link to its own privacy notice and its safeguarding contacts.

curl -X PATCH https://app.zentiqai.com/v1/settings/organization \
  -H "Authorization: Bearer $ZENTIQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "primaryColor": "#0d9488", "country": "US", "timeZone": "America/Chicago" }'

PATCH changes only the fields you send and answers with the settings as they now are. Each field is checked as the console checks it, and a field that doesn't pass is 400 invalid_request with param naming it:

• name: 1 to 80 characters, kept on one line.
• primaryColor, secondaryColor: a 6-digit hex color, like #0d9488.
• logoUrl: a web address starting with http:// or https://; null clears it.
• country: a two-letter country code. It decides the emergency and help lines the avatars give, and the age under which a parent must consent.
• timeZone: an IANA time zone, like Europe/Paris, for the dates in alerts.
• safeguardingContacts: up to 10 email addresses, told at once when someone may not be safe. Sending the list replaces it.
• privacyNoticeUrl: a web address starting with https://.

The safeguarding contacts are people's email addresses, so a key sees them only when it also holds safety:read; otherwise the field is null. The safeguarding settings (safeguardingContacts, country, timeZone and privacyNoticeUrl) change only with safety:write as well, even on a full-access key: an owner or admin gives the safety:* scopes in the console. Changing the consent.mode switch (whether each child needs a guardian's consent) needs people:write as well as settings:write. A change to the country, time zone, privacy notice or safeguarding contacts is recorded as a setting.changed event in the event log. For the safeguarding contacts it records how many there are, never the addresses.

The type of organization (type: school, company, tutoring, individual, family or other) sets the words people see and the recommended value of every switch. Only an owner changes it, in the console: a key acts as an admin, so a PATCH that sends type is 403 forbidden.

Switches#

A switch turns a feature on or off, or chooses how it works: whether team leaders may read conversations, how long a session runs, which maths curriculum the tutor follows. Every switch has a recommended value for the type of organization, which applies until someone sets another.

A switch can be set at three levels:

The nearest level that sets a value wins: a unit's own value, then the unit above it, then the subject, then the organization, then the recommended value. A level may also lock a switch, so that no level below it can change it.

Reading switches#

GET /v1/settings/switches?scope=unit&scopeId=unit_… lists the switches that can be set at that scope. For each one:

• value: what applies there now, on the organization's plan.
• source: where that value comes from (default for the recommended value, or the organization, subject or unit that set it).
• locked and lockedBy: whether a level at or above this one locked it, and which.
• recommended: the recommended value for the type of organization.
• planFeature: set when the plan doesn't include the feature. The switch then stays at its default (a feature the plan doesn't include reads off) and can only be switched off or cleared.
• heldBy: "zero_data_retention": the organization keeps no conversation words, so this switch keeps the value that rule needs and nobody can change it.
• canChange and canLock: whether your key may change or lock it at this scope.

At the organization scope, each switch also lists the values set for single subjects and units (overrides), so you can see where it differs. GET /v1/settings/switches/{key} returns one switch the same way.

{
  "key": "transcripts.leader_view",
  "type": "boolean",
  "value": false,
  "recommended": true,
  "source": { "scope": "organization", "scopeId": "org_…" },
  "locked": true,
  "lockedBy": { "scope": "organization", "scopeId": "org_…" },
  "planFeature": null,
  "heldBy": null,
  "canChange": true,
  "canLock": true,
  "overrides": []
}

Changing switches#

PUT /v1/settings/switches/{key} sets a value at a scope. Add "locked": true to lock it for the levels below; a PUT without it also unlocks it.

curl -X PUT "https://app.zentiqai.com/v1/settings/switches/session.length_minutes?scope=unit&scopeId=unit_…" \
  -H "Authorization: Bearer $ZENTIQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "value": 20 }'

DELETE /v1/settings/switches/{key} removes the value set at a scope, so the level above (or the recommended value) applies again. Both answer with the switch as it now applies at that scope, and each change is recorded as a setting.changed event.

What a key may change#

A key acts as an admin of the organization, so it may change what an admin may change in the console, and nothing more:

• A switch only an owner changes is shown with canChange: false, and changing it is 403 forbidden.
• Some features are switched on by Zentiq for an organization. They are listed only once they are on, and stay Zentiq's to change.
• The API offers the same switches Settings › Features does. A switch the console no longer shows is listed only while it is set at that scope, so it can be cleared.