Skip to main content
PATCH
/
v1
/
api
/
settings
Update workspace settings
curl --request PATCH \
  --url https://api.hq.zone/v1/api/settings \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "allow_guest_signin": true,
  "consent_mode": "<string>",
  "corpus_history_days": 123,
  "nudge_end_hour": 123,
  "nudge_fallback_lang": "<string>",
  "nudge_start_hour": 123,
  "nudge_tz": "<string>",
  "proactive_nudges_enabled": true,
  "profile_mode": "<string>",
  "signin_mode": "<string>"
}
'
{
  "allow_guest_signin": true,
  "consent_mode": "<string>",
  "corpus_history_days": 123,
  "nudge_end_hour": 123,
  "nudge_start_hour": 123,
  "proactive_nudges_enabled": true,
  "profile_mode": "<string>",
  "signin_mode": "<string>",
  "source_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "source_kind": "<string>",
  "nudge_fallback_lang": "<string>",
  "nudge_tz": "<string>",
  "source_workspace": "<string>"
}

Authorizations

​
Authorization
string
header
required

Personal Access Token. Send as Authorization: Bearer hq_pat_....

Body

application/json
​
allow_guest_signin
boolean | null
​
consent_mode
string | null
​
corpus_history_days
integer<int32> | null
​
nudge_end_hour
integer<int32> | null
​
nudge_fallback_lang
string | null

Empty string clears (revert to derived/default); absent leaves unchanged.

​
nudge_start_hour
integer<int32> | null
​
nudge_tz
string | null

Empty string clears (revert to derived/default); absent leaves unchanged.

​
proactive_nudges_enabled
boolean | null
​
profile_mode
string | null
​
signin_mode
string | null

Response

Updated settings

​
allow_guest_signin
boolean
required

Whether Slack guests (single-/multi-channel) may sign in. Default false - guests are blocked unless an admin flips this on (or explicitly allows an individual guest under Users).

​
consent_mode
string
required

admin_only (default - the admin opts in for the whole tenant) or per_user (each user must grant consent before distillation considers their messages).

​
corpus_history_days
integer<int32>
required

How far back the corpus crawler ingests messages. 30–365.

​
nudge_end_hour
integer<int32>
required

Local hour the daily nudge stops, exclusive (1–24, default 18).

​
nudge_start_hour
integer<int32>
required

Local hour the daily nudge may start (0–23, default 9).

​
proactive_nudges_enabled
boolean
required

Whether HQ proactively nudges channels - the one-time welcome plus capped daily "you could connect/turn on X" messages. Default true; admins opt out here.

​
profile_mode
string
required

enabled / disabled. When enabled, the profile worker runs every tick and distils a per-user persona doc from the messages_corpus table.

​
signin_mode
string
required

Who in the connected workspace may sign in to HQ (migration 0129): open (default - any workspace member, minus explicit denies) or approval (allowlist - only users an admin has explicitly allowed).

​
source_id
string<uuid>
required

workspace_corpus_sources.id for the (single) connected source. Surfaced so the UI knows what it's editing; the PATCH endpoint scopes by tenant slug, not by id.

​
source_kind
string
required

Connector kind - slack / teams / manual. Read-only.

​
nudge_fallback_lang
string | null

BCP-47 language HQ falls back to when a channel is too quiet to detect one. null = Slack workspace locale, else English.

​
nudge_tz
string | null

IANA timezone the daily nudge schedules in (e.g. Europe/Stockholm). null = derive from the connected workspace, else UTC. Set this for a web-only tenant with no Slack to derive a tz from.

​
source_workspace
string | null

Display name of the connected workspace (e.g. "Truespar"). Read-only.