> ## Documentation Index > Fetch the complete documentation index at: https://docs.hq.zone/llms.txt > Use this file to discover all available pages before exploring further. # Update workspace settings > Updates the workspace-level settings an admin controls and returns the full updated settings. Admin only. Any subset of fields may be supplied; omitted fields are left unchanged, and for the nudge timezone and fallback language an empty string reverts to the default. Validates allowed values and ranges (for example profile_mode must be enabled or disabled, consent_mode admin_only or per_user, corpus_history_days 30-365, sign-in mode open or approval, and nudge start hour before end hour), returning 400 on an invalid value and 403 for non-admins. ## OpenAPI ````yaml PATCH /v1/api/settings openapi: 3.1.0 info: title: HQ API description: >- Public HTTP API for HQ. Authenticate with a Personal Access Token (`Authorization: Bearer hq_pat_...`) for server-side integrations, or an OAuth 2.1 authorization-code + PKCE flow for browser apps acting on a user's behalf. Both grant from the same resource:action scope vocabulary; an endpoint's required scope is listed under its `security`. license: name: Apache-2.0 identifier: Apache-2.0 version: 1.0.0 servers: - url: https://api.hq.zone description: HQ API (production) security: [] tags: - name: me description: The signed-in user's own account - name: conversations description: Conversations and their messages - name: documents description: The content-addressed documents library - name: schedules description: Scheduled prompts and recurring tasks - name: agents description: Agents, their skills and integrations - name: memory description: What the assistant remembers (L5 governance) - name: tokens description: Personal Access Token management - name: billing description: Usage and billing - name: notifications description: In-app notification center - name: admin description: Workspace administration - name: integrations description: Workspace integrations (Slack, MCP, skills) - name: onboarding description: New-workspace onboarding wizard - name: auth description: Sign-in, sessions, and OAuth paths: /v1/api/settings: patch: tags: - admin summary: Update workspace settings description: >- Updates the workspace-level settings an admin controls and returns the full updated settings. Admin only. Any subset of fields may be supplied; omitted fields are left unchanged, and for the nudge timezone and fallback language an empty string reverts to the default. Validates allowed values and ranges (for example profile_mode must be enabled or disabled, consent_mode admin_only or per_user, corpus_history_days 30-365, sign-in mode open or approval, and nudge start hour before end hour), returning 400 on an invalid value and 403 for non-admins. operationId: update_settings requestBody: content: application/json: schema: $ref: '#/components/schemas/SettingsPatchReq' required: true responses: '200': description: Updated settings content: application/json: schema: $ref: '#/components/schemas/SettingsResp' '400': description: Invalid field value '403': description: Admin role required security: - bearer_pat: - admin - oauth2: - admin components: schemas: SettingsPatchReq: type: object properties: allow_guest_signin: type: - boolean - 'null' channel_tips_enabled: type: - boolean - 'null' consent_mode: type: - string - 'null' corpus_history_days: type: - integer - 'null' format: int32 default_locale: type: - string - 'null' description: >- Workspace-wide default UI language (BCP-47-ish, e.g. `en` / `sv`). Absent leaves it unchanged. Cannot be cleared - the column is NOT NULL. nudge_end_hour: type: - integer - 'null' format: int32 nudge_fallback_lang: type: - string - 'null' description: >- Empty string clears (revert to derived/default); absent leaves unchanged. nudge_start_hour: type: - integer - 'null' format: int32 nudge_tz: type: - string - 'null' description: >- Empty string clears (revert to derived/default); absent leaves unchanged. proactive_nudges_enabled: type: - boolean - 'null' profile_mode: type: - string - 'null' signin_mode: type: - string - 'null' SettingsResp: type: object required: - source_id - source_kind - default_locale - profile_mode - consent_mode - corpus_history_days - signin_mode - allow_guest_signin - proactive_nudges_enabled - channel_tips_enabled - nudge_start_hour - nudge_end_hour properties: allow_guest_signin: type: boolean description: |- 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). channel_tips_enabled: type: boolean description: >- Whether HQ posts RECURRING skill/integration recommendations in active channels (separate from the one-time welcome). Default `false` - an admin opts in. Only effective when `proactive_nudges_enabled` is on. consent_mode: type: string description: |- `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: type: integer format: int32 description: How far back the corpus crawler ingests messages. 30–365. default_locale: type: string description: >- Workspace-wide default UI language (`tenants.default_locale`). The fallback for members with no locale of their own; the i18n resolver falls back to English if this names a language with no UI translation. nudge_end_hour: type: integer format: int32 description: Local hour the daily nudge stops, exclusive (1–24, default 18). nudge_fallback_lang: type: - string - 'null' description: >- BCP-47 language HQ falls back to when a channel is too quiet to detect one. `null` = Slack workspace locale, else English. nudge_start_hour: type: integer format: int32 description: Local hour the daily nudge may start (0–23, default 9). nudge_tz: type: - string - 'null' description: >- 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. proactive_nudges_enabled: type: boolean description: >- Master switch for HQ posting in channels unprompted - in practice the one-time join welcome. Default `true`; admins opt out here. Also gates the recurring recommendations below (those need this on). profile_mode: type: string description: |- `enabled` / `disabled`. When `enabled`, the profile worker runs every tick and distils a per-user persona doc from the `messages_corpus` table. signin_mode: type: string description: |- 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: type: string format: uuid description: |- `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: type: string description: Connector kind - `slack` / `teams` / `manual`. Read-only. source_workspace: type: - string - 'null' description: >- Display name of the connected workspace (e.g. "Truespar"). Read-only. securitySchemes: bearer_pat: type: http scheme: bearer bearerFormat: hq_pat description: 'Personal Access Token. Send as `Authorization: Bearer hq_pat_...`.' oauth2: type: oauth2 flows: authorizationCode: authorizationUrl: https://app.hq.zone/v1/oauth/authorize tokenUrl: https://api.hq.zone/v1/oauth/token refreshUrl: https://api.hq.zone/v1/oauth/token scopes: admin: Administer the workspace (users, settings, integrations) agents:read: View the agents in your workspace agents:write: Create and configure agents billing:read: View usage and billing information conversations:read: Read your conversations and their messages conversations:write: Start conversations and send messages on your behalf documents:read: Read your documents library documents:write: Upload and manage documents in your library memory:read: Read what the assistant remembers about you memory:write: Correct or delete what the assistant remembers schedules:read: View your scheduled tasks schedules:write: Create and manage scheduled tasks tables:read: Read your tables and their rows tables:write: Create tables and add, edit, or delete rows ````