> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/open-webui/open-webui/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Channel

> Create a new channel

Creates a new channel. The type of channel determines who can create it and how it behaves:

* `dm` - Direct message channel between users
* `group` - Private group channel with invited members
* `standard` - Public or restricted channel (admin only)

## Authentication

Requires a valid user session. Admin role required for creating `standard` channels.

## Request Body

<ParamField body="type" type="string">
  Channel type: `dm`, `group`, or `standard`. Only admins can create `standard` channels.
</ParamField>

<ParamField body="name" type="string" required>
  Channel name (can be empty for DM channels)
</ParamField>

<ParamField body="description" type="string">
  Channel description
</ParamField>

<ParamField body="is_private" type="boolean">
  Whether the channel is private (for group channels)
</ParamField>

<ParamField body="user_ids" type="array">
  Array of user IDs to invite to the channel
</ParamField>

<ParamField body="group_ids" type="array">
  Array of group IDs to grant access to the channel
</ParamField>

<ParamField body="access_grants" type="array">
  Access control grants for the channel

  <Expandable title="Access Grant Object">
    <ParamField body="principal_type" type="string" required>
      Type of principal: `user`, `group`, or `role`
    </ParamField>

    <ParamField body="principal_id" type="string" required>
      ID of the principal, or `*` for public access
    </ParamField>

    <ParamField body="permission" type="string" required>
      Permission level: `read` or `write`
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="data" type="object">
  Additional channel data
</ParamField>

<ParamField body="meta" type="object">
  Channel metadata
</ParamField>

## Response

Returns the created channel object.

<ResponseField name="id" type="string" required>
  Unique channel identifier
</ResponseField>

<ResponseField name="user_id" type="string" required>
  ID of the user who created the channel
</ResponseField>

<ResponseField name="type" type="string">
  Channel type
</ResponseField>

<ResponseField name="name" type="string" required>
  Channel name
</ResponseField>

<ResponseField name="description" type="string">
  Channel description
</ResponseField>

<ResponseField name="is_private" type="boolean">
  Whether the channel is private
</ResponseField>

<ResponseField name="access_grants" type="array">
  Access control grants
</ResponseField>

<ResponseField name="created_at" type="integer" required>
  Creation timestamp (epoch time in nanoseconds)
</ResponseField>

<ResponseField name="updated_at" type="integer" required>
  Last update timestamp (epoch time in nanoseconds)
</ResponseField>

<RequestExample>
  ```bash Create Standard Channel theme={null}
  curl -X POST "https://your-domain.com/api/channels/create" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "standard",
      "name": "announcements",
      "description": "Official announcements",
      "access_grants": [
        {
          "principal_type": "user",
          "principal_id": "*",
          "permission": "read"
        },
        {
          "principal_type": "role",
          "principal_id": "admin",
          "permission": "write"
        }
      ]
    }'
  ```

  ```bash Create DM Channel theme={null}
  curl -X POST "https://your-domain.com/api/channels/create" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "dm",
      "name": "",
      "user_ids": ["user_456"]
    }'
  ```

  ```bash Create Group Channel theme={null}
  curl -X POST "https://your-domain.com/api/channels/create" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "group",
      "name": "Project Team",
      "description": "Private team discussion",
      "is_private": true,
      "user_ids": ["user_456", "user_789"],
      "group_ids": ["group_123"]
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://your-domain.com/api/channels/create",
      headers={"Authorization": "Bearer YOUR_TOKEN"},
      json={
          "type": "group",
          "name": "Engineering",
          "description": "Engineering team discussions",
          "is_private": True,
          "user_ids": ["user_456", "user_789"]
      }
  )

  channel = response.json()
  print(f"Created channel: {channel['id']}")
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "id": "ch_abc123",
    "user_id": "user_123",
    "type": "standard",
    "name": "announcements",
    "description": "Official announcements",
    "is_private": false,
    "data": null,
    "meta": null,
    "access_grants": [
      {
        "principal_type": "user",
        "principal_id": "*",
        "permission": "read"
      },
      {
        "principal_type": "role",
        "principal_id": "admin",
        "permission": "write"
      }
    ],
    "created_at": 1709567890123456789,
    "updated_at": 1709567890123456789,
    "updated_by": null,
    "archived_at": null,
    "archived_by": null,
    "deleted_at": null,
    "deleted_by": null
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "detail": "Unauthorized"
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "detail": "ERROR"
  }
  ```
</ResponseExample>

## Notes

* For DM channels, if a channel already exists between the specified users, the existing channel is returned instead of creating a duplicate
* The creator is automatically added as a member of the channel with manager role
* Only admins can create `standard` type channels
* Members are automatically added to the channel's socket room for real-time updates