---
title: "Create User Group"
method: POST
path: "/manage/admin/user-group"
tags: ["public"]
---

# Create User Group

`POST /manage/admin/user-group`

## Request

- Base URL: `https://cloud.onyx.app/api`
- URL: `https://cloud.onyx.app/api/manage/admin/user-group`
- Auth: HTTP bearer

## Request body

- UserGroupCreate
  - `name` string, required
  - `user_ids` string[], required
  - `cc_pair_ids` integer[], required

## Response `200`

Successful Response

- UserGroup
  - `id` integer, required
  - `name` string, required
  - `users` UserInfo[], required
    - `id` string, required
    - `email` string, required
    - `is_active` boolean, required
    - `is_superuser` boolean, required
    - `is_verified` boolean, required
    - `account_type` 'STANDARD' | 'BOT' | 'EXT_PERM_USER' | 'SERVICE_ACCOUNT' | 'ANONYMOUS': What kind of account this is — determines whether the user enters the group-based permission system. STANDARD + SERVICE_ACCOUNT → participate in group system BOT, EXT_PERM_USER, ANONYMOUS → fixed behavior
    - `preferences` UserPreferences, required
      - `chosen_assistants` integer[], nullable
      - `hidden_assistants` integer[]
      - `visible_assistants` integer[]
      - `default_model` string, nullable
      - `pinned_assistants` integer[]
      - `shortcut_enabled` boolean, nullable
      - `auto_scroll` boolean, nullable
      - `temperature_override_enabled` boolean, nullable
      - `temperature_default` number, nullable
      - `reasoning_effort_default` 'auto' | 'off' | 'low' | 'medium' | 'high' | 'xhigh': Reasoning effort levels for models that support extended thinking. Different providers map these values differently: - OpenAI: Uses "low", "medium", "high" directly for reasoning_effort. Recently added "none" for 5 series which is like "minimal" - Claude: Uses budget_tokens with different values for each level - Gemini: Uses "none", "low", "medium", "high" for thinking_budget (via litellm mapping)
      - `theme_preference` 'light' | 'dark' | 'system'
      - `language` string, nullable
      - `chat_background` string, nullable
      - `default_app_mode` 'AUTO' | 'CHAT' | 'SEARCH'
      - `paste_as_tile` boolean, nullable
      - `voice_auto_send` boolean, nullable
      - `voice_auto_playback` boolean, nullable
      - `voice_playback_speed` number, nullable
      - `assistant_specific_configs` object, nullable
    - `personalization` UserPersonalization
      - `name` string
      - `role` string
      - `use_memories` boolean
      - `enable_memory_tool` boolean
      - `memories` MemoryItem[]
        - `id` integer, nullable
        - `content` string, required
      - `user_preferences` string
    - `token_expires_at` string, date-time, nullable
    - `is_cloud_superuser` boolean
    - `team_name` string, nullable
    - `is_anonymous_user` boolean, nullable
    - `password_configured` boolean, nullable
    - `tenant_info` TenantInfo
      - `invitation` TenantSnapshot
        - `number_of_users` integer, required
      - `new_tenant` TenantSnapshot
        - `number_of_users` integer, required
    - `effective_permissions` string[]
    - `is_group_manager` boolean
    - `admin_capabilities` string[]
  - `manager_ids` string[], required
  - `cc_pairs` ConnectorCredentialPairDescriptor[], required
    - `id` integer, required
    - `name` string, required
    - `connector` ConnectorSnapshot, required
      - `name` string, required
      - `source` 'ingestion_api' | 'slack' | 'web' | 'google_drive' | 'gmail' | 'github' | 'gitbook' | 'gitlab' | 'guru' | 'bookstack' | 'outline' | 'confluence' | 'jira' | 'slab' | 'productboard' | 'file' | 'coda' | 'canvas' | 'notion' | 'zulip' | 'linear' | 'hubspot' | 'document360' | 'gong' | 'google_sites' | 'zendesk' | 'loopio' | 'box' | 'dropbox' | 'sharepoint' | 'onedrive' | 'teams' | 'outlook' | 'salesforce' | 'discourse' | 'axero' | 'clickup' | 'mediawiki' | 'wikipedia' | 'asana' | 's3' | 'r2' | 'google_cloud_storage' | 'oci_storage' | 'xenforo' | 'not_applicable' | 'discord' | 'freshdesk' | 'fireflies' | 'zoom' | 'egnyte' | 'airtable' | 'highspot' | 'drupal_wiki' | 'imap' | 'bitbucket' | 'testrail' | 'braintrust' | 'lumapps' | 'youtrack' | 'mock_connector' | 'user_file' | 'craft_file', required
      - `input_type` 'load_state' | 'poll' | 'event' | 'slim_retrieval', required
      - `connector_specific_config` object, required
      - `refresh_freq` integer, nullable
      - `prune_freq` integer, nullable
      - `check_freq` integer, nullable
      - `indexing_start` string, date-time, nullable
      - `id` integer, required
      - `credential_ids` integer[], required
      - `time_created` string, date-time, required
      - `time_updated` string, date-time, required
    - `credential` CredentialSnapshot, required
      - `credential_json` object, required
      - `admin_public` boolean, required
      - `source` 'ingestion_api' | 'slack' | 'web' | 'google_drive' | 'gmail' | 'github' | 'gitbook' | 'gitlab' | 'guru' | 'bookstack' | 'outline' | 'confluence' | 'jira' | 'slab' | 'productboard' | 'file' | 'coda' | 'canvas' | 'notion' | 'zulip' | 'linear' | 'hubspot' | 'document360' | 'gong' | 'google_sites' | 'zendesk' | 'loopio' | 'box' | 'dropbox' | 'sharepoint' | 'onedrive' | 'teams' | 'outlook' | 'salesforce' | 'discourse' | 'axero' | 'clickup' | 'mediawiki' | 'wikipedia' | 'asana' | 's3' | 'r2' | 'google_cloud_storage' | 'oci_storage' | 'xenforo' | 'not_applicable' | 'discord' | 'freshdesk' | 'fireflies' | 'zoom' | 'egnyte' | 'airtable' | 'highspot' | 'drupal_wiki' | 'imap' | 'bitbucket' | 'testrail' | 'braintrust' | 'lumapps' | 'youtrack' | 'mock_connector' | 'user_file' | 'craft_file', required
      - `name` string, nullable
      - `curator_public` boolean
      - `groups` integer[]
      - `id` integer, required
      - `user_id` string, uuid, nullable, required
      - `user_email` string, nullable
      - `user_personal_name` string, nullable
      - `time_created` string, date-time, required
      - `time_updated` string, date-time, required
      - `is_owner` boolean, nullable
    - `access_type` 'public' | 'private' | 'sync' | 'sync_restricted', required
  - `managed_cc_pairs` ManagedCCPairEntry[], required
    - `cc_pair_id` integer, required
    - `role` 'editor' | 'operator': A group's role on a cc-pair it manages. Editors change and delete the configuration; Operators schedule and monitor indexing.
  - `document_sets` DocumentSet[], required
    - `id` integer, required
    - `name` string, required
    - `description` string, nullable, required
    - `cc_pair_descriptors` ConnectorCredentialPairDescriptor[], required
      - `id` integer, required
      - `name` string, required
      - `connector` ConnectorSnapshot, required
        - `name` string, required
        - `source` 'ingestion_api' | 'slack' | 'web' | 'google_drive' | 'gmail' | 'github' | 'gitbook' | 'gitlab' | 'guru' | 'bookstack' | 'outline' | 'confluence' | 'jira' | 'slab' | 'productboard' | 'file' | 'coda' | 'canvas' | 'notion' | 'zulip' | 'linear' | 'hubspot' | 'document360' | 'gong' | 'google_sites' | 'zendesk' | 'loopio' | 'box' | 'dropbox' | 'sharepoint' | 'onedrive' | 'teams' | 'outlook' | 'salesforce' | 'discourse' | 'axero' | 'clickup' | 'mediawiki' | 'wikipedia' | 'asana' | 's3' | 'r2' | 'google_cloud_storage' | 'oci_storage' | 'xenforo' | 'not_applicable' | 'discord' | 'freshdesk' | 'fireflies' | 'zoom' | 'egnyte' | 'airtable' | 'highspot' | 'drupal_wiki' | 'imap' | 'bitbucket' | 'testrail' | 'braintrust' | 'lumapps' | 'youtrack' | 'mock_connector' | 'user_file' | 'craft_file', required
        - `input_type` 'load_state' | 'poll' | 'event' | 'slim_retrieval', required
        - `connector_specific_config` object, required
        - `refresh_freq` integer, nullable
        - `prune_freq` integer, nullable
        - `check_freq` integer, nullable
        - `indexing_start` string, date-time, nullable
        - `id` integer, required
        - `credential_ids` integer[], required
        - `time_created` string, date-time, required
        - `time_updated` string, date-time, required
      - `credential` CredentialSnapshot, required
        - `credential_json` object, required
        - `admin_public` boolean, required
        - `source` 'ingestion_api' | 'slack' | 'web' | 'google_drive' | 'gmail' | 'github' | 'gitbook' | 'gitlab' | 'guru' | 'bookstack' | 'outline' | 'confluence' | 'jira' | 'slab' | 'productboard' | 'file' | 'coda' | 'canvas' | 'notion' | 'zulip' | 'linear' | 'hubspot' | 'document360' | 'gong' | 'google_sites' | 'zendesk' | 'loopio' | 'box' | 'dropbox' | 'sharepoint' | 'onedrive' | 'teams' | 'outlook' | 'salesforce' | 'discourse' | 'axero' | 'clickup' | 'mediawiki' | 'wikipedia' | 'asana' | 's3' | 'r2' | 'google_cloud_storage' | 'oci_storage' | 'xenforo' | 'not_applicable' | 'discord' | 'freshdesk' | 'fireflies' | 'zoom' | 'egnyte' | 'airtable' | 'highspot' | 'drupal_wiki' | 'imap' | 'bitbucket' | 'testrail' | 'braintrust' | 'lumapps' | 'youtrack' | 'mock_connector' | 'user_file' | 'craft_file', required
        - `name` string, nullable
        - `curator_public` boolean
        - `groups` integer[]
        - `id` integer, required
        - `user_id` string, uuid, nullable, required
        - `user_email` string, nullable
        - `user_personal_name` string, nullable
        - `time_created` string, date-time, required
        - `time_updated` string, date-time, required
        - `is_owner` boolean, nullable
      - `access_type` 'public' | 'private' | 'sync' | 'sync_restricted', required
    - `is_up_to_date` boolean, required
    - `is_public` boolean, required
    - `users` string[], required
    - `groups` integer[], required
    - `federated_connectors` FederatedConnectorDescriptor[]
      - `id` integer, required
      - `name` string, required
      - `source` string, required
      - `entities` object, required
  - `personas` PersonaSnapshot[], required
    - `id` integer, required
    - `name` string, required
    - `description` string, required
    - `is_public` boolean, required
    - `is_listed` boolean, required
    - `uploaded_image_id` string, nullable, required
    - `icon_name` string, nullable, required
    - `user_file_ids` string[], required
    - `display_priority` integer, nullable, required
    - `is_featured` boolean, required
    - `builtin_persona` boolean, required
    - `starter_messages` StarterMessage[], nullable, required
      - `name` string, required
      - `message` string, required
    - `tools` ToolSnapshot[], required
      - `id` integer, required
      - `name` string, required
      - `description` string, required
      - `definition` object, nullable, required
      - `display_name` string, required
      - `in_code_tool_id` string, nullable, required
      - `custom_headers` unknown[], nullable, required
        - unknown
      - `passthrough_auth` boolean, required
      - `mcp_server_id` integer, nullable
      - `user_id` string, nullable
      - `oauth_config_id` integer, nullable
      - `oauth_config_name` string, nullable
      - `enabled` boolean
      - `user_enabled_in_chat` boolean
      - `default_chat_enabled` boolean, nullable: Whether this tool is selected for the default assistant.
      - `permissions` object
      - `chat_selectable` boolean
      - `agent_creation_selectable` boolean
      - `default_enabled` boolean
    - `labels` PersonaLabelSnapshot[], required
      - `id` integer, required
      - `name` string, required
    - `owner` MinimalUserSnapshot, required
      - `id` string, uuid, required
      - `email` string, required
    - `owner_group` PersonaOwnerGroupSnapshot, required
      - `id` integer, required
      - `name` string, required
    - `users` MinimalUserSnapshot[], required
      - `id` string, uuid, required
      - `email` string, required
    - `groups` integer[], required
    - `user_shares` PersonaUserShare[], required
      - `user` MinimalUserSnapshot, required
        - `id` string, uuid, required
        - `email` string, required
      - `permission` 'EDITOR' | 'VIEWER', required: Level granted by a persona share row (user or group), or to the whole org via `Persona.public_permission`.
    - `group_shares` PersonaGroupShare[], required
      - `group_id` integer, required
      - `group_name` string, required
      - `permission` 'EDITOR' | 'VIEWER', required: Level granted by a persona share row (user or group), or to the whole org via `Persona.public_permission`.
    - `public_permission` 'EDITOR' | 'VIEWER', required: Level granted by a persona share row (user or group), or to the whole org via `Persona.public_permission`.
    - `sharing_status` 'PRIVATE' | 'SHARED' | 'PUBLIC', required: Derived share state computed from a persona's columns by the sharing helpers (no DB column of its own): group-owned or row-shared counts as SHARED even with an empty share list; PUBLIC wins over both.
    - `document_sets` DocumentSetSummary[], required
      - `id` integer, required
      - `name` string, required
      - `description` string, nullable, required
      - `cc_pair_summaries` CCPairSummary[], required
        - `id` integer, required
        - `name` string, required
        - `source` 'ingestion_api' | 'slack' | 'web' | 'google_drive' | 'gmail' | 'github' | 'gitbook' | 'gitlab' | 'guru' | 'bookstack' | 'outline' | 'confluence' | 'jira' | 'slab' | 'productboard' | 'file' | 'coda' | 'canvas' | 'notion' | 'zulip' | 'linear' | 'hubspot' | 'document360' | 'gong' | 'google_sites' | 'zendesk' | 'loopio' | 'box' | 'dropbox' | 'sharepoint' | 'onedrive' | 'teams' | 'outlook' | 'salesforce' | 'discourse' | 'axero' | 'clickup' | 'mediawiki' | 'wikipedia' | 'asana' | 's3' | 'r2' | 'google_cloud_storage' | 'oci_storage' | 'xenforo' | 'not_applicable' | 'discord' | 'freshdesk' | 'fireflies' | 'zoom' | 'egnyte' | 'airtable' | 'highspot' | 'drupal_wiki' | 'imap' | 'bitbucket' | 'testrail' | 'braintrust' | 'lumapps' | 'youtrack' | 'mock_connector' | 'user_file' | 'craft_file', required
        - `access_type` 'public' | 'private' | 'sync' | 'sync_restricted', required
      - `is_up_to_date` boolean, required
      - `is_public` boolean, required
      - `users` string[], required
      - `groups` integer[], required
      - `permissions` object
      - `federated_connector_summaries` FederatedConnectorSummary[]
        - `id` integer, required
        - `name` string, required
        - `source` 'federated_slack', required
        - `entities` object, required
    - `default_model_configuration_id` integer, nullable
    - `hierarchy_nodes` HierarchyNodeSnapshot[]
      - `id` integer, required
      - `raw_node_id` string, required
      - `display_name` string, required
      - `link` string, nullable, required
      - `source` 'ingestion_api' | 'slack' | 'web' | 'google_drive' | 'gmail' | 'github' | 'gitbook' | 'gitlab' | 'guru' | 'bookstack' | 'outline' | 'confluence' | 'jira' | 'slab' | 'productboard' | 'file' | 'coda' | 'canvas' | 'notion' | 'zulip' | 'linear' | 'hubspot' | 'document360' | 'gong' | 'google_sites' | 'zendesk' | 'loopio' | 'box' | 'dropbox' | 'sharepoint' | 'onedrive' | 'teams' | 'outlook' | 'salesforce' | 'discourse' | 'axero' | 'clickup' | 'mediawiki' | 'wikipedia' | 'asana' | 's3' | 'r2' | 'google_cloud_storage' | 'oci_storage' | 'xenforo' | 'not_applicable' | 'discord' | 'freshdesk' | 'fireflies' | 'zoom' | 'egnyte' | 'airtable' | 'highspot' | 'drupal_wiki' | 'imap' | 'bitbucket' | 'testrail' | 'braintrust' | 'lumapps' | 'youtrack' | 'mock_connector' | 'user_file' | 'craft_file', required
      - `node_type` 'folder' | 'source' | 'stub' | 'shared_drive' | 'my_drive' | 'space' | 'page' | 'project' | 'database' | 'workspace' | 'site' | 'drive' | 'channel' | 'mailbox', required: Types of hierarchy nodes across different sources
    - `attached_documents` AttachedDocumentSnapshot[]
      - `id` string, required
      - `title` string, required
      - `link` string, nullable, required
      - `parent_id` integer, nullable, required
      - `last_modified` string, date-time, nullable, required
      - `last_synced` string, date-time, nullable, required
      - `source` 'ingestion_api' | 'slack' | 'web' | 'google_drive' | 'gmail' | 'github' | 'gitbook' | 'gitlab' | 'guru' | 'bookstack' | 'outline' | 'confluence' | 'jira' | 'slab' | 'productboard' | 'file' | 'coda' | 'canvas' | 'notion' | 'zulip' | 'linear' | 'hubspot' | 'document360' | 'gong' | 'google_sites' | 'zendesk' | 'loopio' | 'box' | 'dropbox' | 'sharepoint' | 'onedrive' | 'teams' | 'outlook' | 'salesforce' | 'discourse' | 'axero' | 'clickup' | 'mediawiki' | 'wikipedia' | 'asana' | 's3' | 'r2' | 'google_cloud_storage' | 'oci_storage' | 'xenforo' | 'not_applicable' | 'discord' | 'freshdesk' | 'fireflies' | 'zoom' | 'egnyte' | 'airtable' | 'highspot' | 'drupal_wiki' | 'imap' | 'bitbucket' | 'testrail' | 'braintrust' | 'lumapps' | 'youtrack' | 'mock_connector' | 'user_file' | 'craft_file', required
    - `permissions` object
    - `system_prompt` string, nullable
    - `replace_base_system_prompt` boolean
    - `task_prompt` string, nullable
    - `datetime_aware` boolean
  - `is_up_to_date` boolean, required
  - `is_up_for_deletion` boolean, required
  - `is_default` boolean, required
  - `incognito_enabled` boolean, required
  - `permissions` object

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-28** `76bc90bf55b6`: 1 info
  - endpoint added
- **2026-01-06** `2d941ea53eb3`: 1 breaking
  - api path removed without deprecation
- **2025-08-21** `9321c45d93b5`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/onyx-dot-app/apis/onyx-api/changes/manage/admin/user-group/post.md)

---

[API](https://skmtc.dev/onyx-dot-app/apis/onyx-api.md) - [All operations](https://skmtc.dev/onyx-dot-app/apis/onyx-api/llms.txt) - [OpenAPI document](https://skmtc.dev/onyx-dot-app/apis/onyx-api/revisions/76bc90bf55b6?raw)