---
title: "Create a Channel"
method: POST
path: "/api/v3/workspaces/{workspace_id}/chat/channels"
tags: ["Chat"]
---

# Create a Channel

`POST /api/v3/workspaces/{workspace_id}/chat/channels`

This endpoint creates a new Channel not tied to a Space, Folder, or List. If a Channel with the specified name already exists it returns it.

## Path parameters

- `workspace_id` integer, required

## Request body

- ChatCreateChatChannel
  - `description` string — The description for the Chat being created.
  - `name` string, required — The name for the Chat being created.
  - `topic` string — The topic of the Chat being created.
  - `user_ids` string[] — Optionally specify unique user IDs, up to 100.
  - `visibility` 'PUBLIC' | 'PRIVATE' — The visibility of the Chat being created. If not specified, the Chat is PUBLIC.

## Response `200`

- ChatPublicApiChatChannelsControllerCreateChatChannel200Response — The existing Channel that is matching the creation request.
  - `data` ChatChannel, required
    - `id` string, required
    - `name` string, required
    - `description` string, RichText — The full Description of the Channel.
    - `topic` string
    - `type` 'CHANNEL' | 'DM' | 'GROUP_DM', required — The type of the room
    - `visibility` 'PUBLIC' | 'PRIVATE', required — The visibility of the room
    - `parent` ChatRoomParentDTO, required
      - `id` string, required
      - `type` number, required
    - `creator` string, required — ID of the user who created this room
    - `created_at` string, required — Timestamp of when this room was created
    - `updated_at` string, required — Timestamp of the last update in this room - Deprecated in favor of latest_comment_at
    - `workspace_id` string, required — Workspace ID of the chat room
    - `archived` boolean, required
    - `latest_comment_at` string — Timestamp of the last comment in this room. Optional in the case of a new room with no comments yet
    - `is_canonical_channel` boolean — Is this the canonical channel for the parent location?
    - `is_hidden` boolean — Has the user hidden this room from their sidebar? Currently only an option for DM/Group DM.
    - `default_view` ChatDefaultViewDTO
      - `type` number, required
      - `view_id` string, required
      - `standard` boolean, required
    - `channel_type` 1 | 2 | 3 | 4 — Type of channel (chat, project, etc.) aka subcategory_type
    - `counts` ChatLastReadAtData
      - `parent_id` string, required
      - `parent_type` 'approval' | 'attachment' | 'attachmentAccess' | 'banWorkspace' | 'checklist' | 'checklistItem' | 'checklistTemplateAccess' | 'comment' | 'commentThread' | 'commentsLastReadAt' | 'customField' | 'customFieldAccess' | 'customItem' | 'customPermissionLevel' | 'dashboard' | 'dashboardAccess' | 'doc' | 'docAccess' | 'folder' | 'folderDescendantsSet' | 'folderTemplateAccess' | 'form' | 'formulaValue' | 'foundationalJob' | 'goal' | 'goalAccess' | 'goalFolder' | 'goalFolderAccess' | 'hierarchy' | 'list' | 'listDescendantsPoints' | 'listDescendantsSet' | 'listDescendantsTimeEstimates' | 'listTemplateAccess' | 'notepad' | 'page' | 'pageAccess' | 'post' | 'reminder' | 'reminderAccess' | 'rolledUpFieldValue' | 'scheduledComment' | 'space' | 'spaceDescendantsSet' | 'spaceTemplateAccess' | 'task' | 'taskAccess' | 'taskHistory' | 'taskProperty' | 'taskTemplateAccess' | 'template' | 'user' | 'userAccess' | 'userGroup' | 'userHierarchy' | 'userPresence' | 'view' | 'viewAccess' | 'viewTemplateAccess' | 'whiteboard' | 'whiteboardAccess' | 'widget' | 'workscheduleScheduleExceptions' | 'workscheduleWorkweekSchedule' | 'workspace' | 'workspaceDescendantsSet', required — Any object that can be shared in a Workspace. For example, `customField`, `dashboard`, `folder`, `goal`, `goalFolder`, `list`, `space`, `task`, and `view`.
      - `root_parent_id` string, required
      - `root_parent_type` 'approval' | 'attachment' | 'attachmentAccess' | 'banWorkspace' | 'checklist' | 'checklistItem' | 'checklistTemplateAccess' | 'comment' | 'commentThread' | 'commentsLastReadAt' | 'customField' | 'customFieldAccess' | 'customItem' | 'customPermissionLevel' | 'dashboard' | 'dashboardAccess' | 'doc' | 'docAccess' | 'folder' | 'folderDescendantsSet' | 'folderTemplateAccess' | 'form' | 'formulaValue' | 'foundationalJob' | 'goal' | 'goalAccess' | 'goalFolder' | 'goalFolderAccess' | 'hierarchy' | 'list' | 'listDescendantsPoints' | 'listDescendantsSet' | 'listDescendantsTimeEstimates' | 'listTemplateAccess' | 'notepad' | 'page' | 'pageAccess' | 'post' | 'reminder' | 'reminderAccess' | 'rolledUpFieldValue' | 'scheduledComment' | 'space' | 'spaceDescendantsSet' | 'spaceTemplateAccess' | 'task' | 'taskAccess' | 'taskHistory' | 'taskProperty' | 'taskTemplateAccess' | 'template' | 'user' | 'userAccess' | 'userGroup' | 'userHierarchy' | 'userPresence' | 'view' | 'viewAccess' | 'viewTemplateAccess' | 'whiteboard' | 'whiteboardAccess' | 'widget' | 'workscheduleScheduleExceptions' | 'workscheduleWorkweekSchedule' | 'workspace' | 'workspaceDescendantsSet', required — Any object that can be shared in a Workspace. For example, `customField`, `dashboard`, `folder`, `goal`, `goalFolder`, `list`, `space`, `task`, and `view`.
      - `date` number, required — When the user last read comments to this object, set in the past to mark comments as unread. Should be a timestamp in milliseconds.
      - `_version_vector` ChatCommentVersionVector, required
        - `object_id` string, required
        - `object_type` string, required
        - `vector` ChatCommentVector[], required
          - `master_id` number, required
          - `version` number, required
          - `deleted` boolean, required
        - `workspace_id` number, required
      - `version` number — The version of the object when the last read at object was last updated.
      - `has_unread` boolean — Whether the user has unread comments on this object. (Optional)
      - `num_unread` number — How many unread comments there are on this object. (Optional)
      - `latest_comment_at` number — The date of the latest comment on this object. (Optional)
      - `badge_count` number — The badge count for this object. (Optional)
      - `thread_count` number — The number of unread threads on this object. (Optional)
      - `mention_count` number — The number of mentions on this object. (Optional)
      - `last_updated_at` number — The date of the last update to this object. (Optional)
    - `chat_room_category` 'WELCOME_CHANNEL' — The category of the chat room, e.g. a welcome channel, (in the future, maybe) a ClickBot channel, etc.
    - `canvas_id` string — The id of the canvas owned by the chat room, if any
    - `links` ChatChannelLinks, required
      - `members` string, required — The link to the members of the Channel.
      - `followers` string, required — The link to the followers of the Channel.

## Other responses

- `201`
- `default` — Generic Error response

---

[API](https://skmtc.dev/clickup/apis/clickup-api-v2-reference.md) · [All operations](https://skmtc.dev/clickup/apis/clickup-api-v2-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/clickup/clickup-api-v2-reference/revisions/72216f55b952/schema)