/api/v4/channels: get: tags: - channels summary: Get a list of all channels description: | ##### Permissions `manage_system` operationId: GetAllChannels parameters: - name: not_associated_to_group in: query description: A group id to exclude channels that are associated with that group via GroupChannel records. This can also be left blank with `not_associated_to_group=`. schema: type: string - name: page in: query description: The page to select. schema: type: integer default: 0 - name: per_page in: query description: The number of channels per page. schema: type: integer default: 0 - name: exclude_default_channels in: query description: Whether to exclude default channels (ex Town Square, Off-Topic) from the results. schema: type: boolean default: false - name: include_deleted in: query description: Include channels that have been archived. This correlates to the `DeleteAt` flag being set in the database. schema: type: boolean default: false - name: include_total_count in: query description: >- Appends a total count of returned channels inside the response object - ex: `{ "channels": [], "total_count" : 0 }`. schema: type: boolean default: false - name: exclude_policy_constrained in: query schema: type: boolean default: false description: >- If set to true, channels which are part of a data retention policy will be excluded. The `sysconsole_read_compliance` permission is required to use this parameter. __Minimum server version__: 5.35 responses: "200": description: Channel list retrieval successful content: application/json: schema: $ref: "#/components/schemas/ChannelListWithTeamData" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" post: tags: - channels summary: Create a channel description: > Create a new channel. ##### Permissions If creating a public channel, `create_public_channel` permission is required. If creating a private channel, `create_private_channel` permission is required. operationId: CreateChannel requestBody: content: application/json: schema: type: object required: - name - display_name - type - team_id properties: team_id: type: string description: The team ID of the team to create the channel on name: type: string description: The unique handle for the channel, will be present in the channel URL display_name: type: string description: The non-unique UI name for the channel purpose: type: string description: A short description of the purpose of the channel header: type: string description: Markdown-formatted text to display in the header of the channel type: type: string description: "'O' for a public channel, 'P' for a private channel" managed_category_name: type: string description: The name of the managed category to assign this channel to. Requires an Enterprise license and the `ManagedChannelCategories` feature flag to be enabled. default_category_name: type: string description: Default sidebar category name for members when joining this channel. Requires `EnableChannelCategorySorting` to be enabled on the server. description: Channel object to be created required: true responses: "201": description: Channel creation successful content: application/json: schema: $ref: "#/components/schemas/Channel" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" /api/v4/channels/direct: post: tags: - channels summary: Create a direct message channel description: > Create a new direct message channel between two users. ##### Permissions Must be one of the two users and have `create_direct_channel` permission. Having the `manage_system` permission voids the previous requirements. operationId: CreateDirectChannel requestBody: content: application/json: schema: type: array items: type: string minItems: 2 maxItems: 2 description: The two user ids to be in the direct message required: true responses: "201": description: Direct channel creation successful content: application/json: schema: $ref: "#/components/schemas/Channel" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" /api/v4/channels/group: post: tags: - channels summary: Create a group message channel description: > Create a new group message channel to group of users. If the logged in user's id is not included in the list, it will be appended to the end. ##### Permissions Must have `create_group_channel` permission. operationId: CreateGroupChannel requestBody: content: application/json: schema: type: array items: type: string minItems: 3 maxItems: 8 description: User ids to be in the group message channel. required: true responses: "201": description: Group channel creation successful content: application/json: schema: $ref: "#/components/schemas/Channel" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" /api/v4/channels/search: post: tags: - channels summary: Search all private and open type channels across all teams description: > Returns all private and open type channels where 'term' matches on the name, display name, or purpose of the channel. Configured 'default' channels (ex Town Square and Off-Topic) can be excluded from the results with the `exclude_default_channels` boolean parameter. Channels that are associated (via GroupChannel records) to a given group can be excluded from the results with the `not_associated_to_group` parameter and a group id string. operationId: SearchAllChannels parameters: - name: system_console in: query description: > Is the request from system_console. If this is set to true, it filters channels by the logged in user. required: false schema: type: boolean default: true requestBody: content: application/json: schema: type: object required: - term properties: term: type: string description: The string to search in the channel name, display name, and purpose. not_associated_to_group: type: string description: A group id to exclude channels that are associated to that group via GroupChannel records. exclude_default_channels: type: boolean description: Exclude default channels from the results by setting this parameter to true. team_ids: type: array items: type: string description: > Filters results to channels belonging to the given team ids __Minimum server version__: 5.26 group_constrained: type: boolean description: > Filters results to only return channels constrained to a group __Minimum server version__: 5.26 exclude_group_constrained: type: boolean description: > Filters results to exclude channels constrained to a group __Minimum server version__: 5.26 public: type: boolean description: > Filters results to only return Public / Open channels, can be used in conjunction with `private` to return both `public` and `private` channels __Minimum server version__: 5.26 private: type: boolean description: > Filters results to only return Private channels, can be used in conjunction with `public` to return both `private` and `public` channels __Minimum server version__: 5.26 deleted: type: boolean description: > Filters results to only return deleted / archived channels __Minimum server version__: 5.26 page: type: string description: The page number to return, if paginated. If this parameter is not present with the `per_page` parameter then the results will be returned un-paged. per_page: type: string description: The number of entries to return per page, if paginated. If this parameter is not present with the `page` parameter then the results will be returned un-paged. exclude_policy_constrained: type: boolean default: false description: > If set to true, only channels which do not have a granular retention policy assigned to them will be returned. The `sysconsole_read_compliance_data_retention` permission is required to use this parameter. __Minimum server version__: 5.35 include_search_by_id: type: boolean default: false description: > If set to true, returns channels where given search 'term' matches channel ID. __Minimum server version__: 5.35 exclude_remote: type: boolean default: false description: > If set to true, only returns channels that are local to this server. __Minimum server version__: 10.2 description: The search terms and logic to use in the search. required: true responses: "200": description: Paginated channel response. (Note that the non-paginated response—returned if the request body does not contain both `page` and `per_page` fields—is a simple array of channels.) content: application/json: schema: type: object properties: channels: type: array description: The channels that matched the query. items: $ref: "#/components/schemas/Channel" total_count: type: number description: The total number of results, regardless of page and per_page requested. "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" /api/v4/channels/group/search: post: tags: - channels summary: Search Group Channels description: > Get a list of group channels for a user which members' usernames match the search term. __Minimum server version__: 5.14 operationId: SearchGroupChannels requestBody: content: application/json: schema: type: object required: - term properties: term: description: The search term to match against the members' usernames of the group channels type: string description: Search criteria required: true responses: "200": description: Channels search successful content: application/json: schema: type: array items: $ref: "#/components/schemas/Channel" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "/api/v4/teams/{team_id}/channels/ids": post: tags: - channels summary: Get a list of channels by ids description: | Get a list of public channels on a team by id. ##### Permissions `view_team` for the team the channels are on. operationId: GetPublicChannelsByIdsForTeam parameters: - name: team_id in: path description: Team GUID required: true schema: type: string requestBody: content: application/json: schema: type: array items: type: string description: List of channel ids. required: true responses: "200": description: Channel list retrieval successful content: application/json: schema: type: array items: $ref: "#/components/schemas/Channel" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "/api/v4/channels/{channel_id}/timezones": get: tags: - channels summary: Get timezones in a channel description: | Get a list of timezones for the users who are in this channel. __Minimum server version__: 5.6 ##### Permissions Must have the `read_channel` permission. operationId: GetChannelMembersTimezones parameters: - name: channel_id in: path description: Channel GUID required: true schema: type: string responses: "200": description: Timezone retrieval successful content: application/json: schema: type: array items: type: string "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "/api/v4/channels/{channel_id}": get: tags: - channels summary: Get a channel description: | Get channel from the provided channel id string. ##### Permissions `read_channel` permission for the channel. operationId: GetChannel parameters: - name: channel_id in: path description: Channel GUID required: true schema: type: string responses: "200": description: Channel retrieval successful content: application/json: schema: $ref: "#/components/schemas/Channel" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" put: tags: - channels summary: Update a channel description: > Update a channel. The fields that can be updated are listed as parameters. Omitted fields will be treated as blanks. ##### Permissions If updating a public channel, `manage_public_channel_members` permission is required. If updating a private channel, `manage_private_channel_members` permission is required. operationId: UpdateChannel parameters: - name: channel_id in: path description: Channel GUID required: true schema: type: string requestBody: content: application/json: schema: type: object required: - id properties: id: type: string description: The channel's id, not updatable name: type: string description: The unique handle for the channel, will be present in the channel URL display_name: type: string description: The non-unique UI name for the channel purpose: type: string description: A short description of the purpose of the channel header: type: string description: Markdown-formatted text to display in the header of the channel description: Channel object to be updated required: true responses: "200": description: Channel update successful content: application/json: schema: $ref: "#/components/schemas/Channel" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" delete: tags: - channels summary: Delete a channel description: > Archives a channel. This will set the `deleteAt` to the current timestamp in the database. Soft deleted channels may not be accessible in the user interface. They can be viewed and unarchived in the **System Console > User Management > Channels** based on your license. Direct and group message channels cannot be deleted. As of server version 5.28, optionally use the `permanent=true` query parameter to permanently delete the channel for compliance reasons. To use this feature `ServiceSettings.EnableAPIChannelDeletion` must be set to `true` in the server's configuration. If you permanently delete a channel this action is not recoverable outside of a database backup. ##### Permissions `delete_public_channel` permission if the channel is public, `delete_private_channel` permission if the channel is private, or have `manage_system` permission. operationId: DeleteChannel parameters: - name: channel_id in: path description: Channel GUID required: true schema: type: string responses: "200": description: Channel deletion successful content: application/json: schema: $ref: "#/components/schemas/StatusOK" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "/api/v4/channels/{channel_id}/patch": put: tags: - channels summary: Patch a channel description: > Partially update a channel by providing only the fields you want to update. Omitted fields will not be updated. At least one of the allowed fields must be provided. **Public and private channels:** Can update `name`, `display_name`, `purpose`, `header`, `group_constrained`, `autotranslation`, and `banner_info` (subject to permissions and channel type). **Direct and group message channels:** Only `header` and (when not restricted by config) `autotranslation` can be updated; the caller must be a channel member. Updating `name`, `display_name`, or `purpose` is not allowed. The default channel (e.g. Town Square) cannot have its `name` changed. ##### Permissions - **Public channel:** For property updates (name, display_name, purpose, header, group_constrained), `manage_public_channel_properties` is required. For `autotranslation`, `manage_public_channel_auto_translation` is required. For `banner_info`, `manage_public_channel_banner` is required (Channel Banner feature and Enterprise license required). - **Private channel:** For property updates, `manage_private_channel_properties` is required. For `autotranslation`, `manage_private_channel_auto_translation` is required. For `banner_info`, `manage_private_channel_banner` is required (Channel Banner feature and Enterprise license required). - **Direct or group message channel:** Must be a member of the channel; only `header` and (when allowed) `autotranslation` can be updated. operationId: PatchChannel parameters: - name: channel_id in: path description: Channel ID required: true schema: type: string requestBody: content: application/json: schema: type: object properties: name: type: string description: The unique handle for the channel, will be present in the channel URL. Cannot be updated for direct or group message channels. Cannot be changed for the default channel (e.g. Town Square). display_name: type: string description: The non-unique UI name for the channel. Cannot be updated for direct or group message channels. purpose: type: string description: A short description of the purpose of the channel. Cannot be updated for direct or group message channels. header: type: string description: Markdown-formatted text to display in the header of the channel group_constrained: type: boolean description: When true, only members of the linked LDAP groups can join the channel. Only applicable to public and private channels. autotranslation: type: boolean description: Enable or disable automatic message translation in the channel. Requires the auto-translation feature and appropriate channel permission. May be restricted for direct and group message channels by server configuration. banner_info: $ref: "#/components/schemas/ChannelBanner" managed_category_name: type: string description: The name of the managed category to assign this channel to. Set to an empty string to clear. Requires an Enterprise license and the `ManagedChannelCategories` feature flag to be enabled. default_category_name: type: string description: Default sidebar category name for members when joining this channel. Set to an empty string to clear. Requires `EnableChannelCategorySorting` to be enabled on the server. description: Channel patch object; include only the fields to update. At least one field must be provided. required: true responses: "200": description: Channel patch successful content: application/json: schema: $ref: "#/components/schemas/Channel" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "/api/v4/channels/{channel_id}/privacy": put: tags: - channels summary: Update channel's privacy description: > Updates channel's privacy allowing changing a channel from Public to Private and back. __Minimum server version__: 5.16 ##### Permissions `manage_team` permission for the channels team on version < 5.28. `convert_public_channel_to_private` permission for the channel if updating privacy to 'P' on version >= 5.28. `convert_private_channel_to_public` permission for the channel if updating privacy to 'O' on version >= 5.28. operationId: UpdateChannelPrivacy parameters: - name: channel_id in: path description: Channel GUID required: true schema: type: string requestBody: content: application/json: schema: type: object required: - privacy properties: privacy: type: string description: "Channel privacy setting: 'O' for a public channel, 'P' for a private channel" required: true responses: "200": description: Channel conversion successful content: application/json: schema: $ref: "#/components/schemas/Channel" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "/api/v4/channels/{channel_id}/restore": post: tags: - channels summary: Restore a channel description: | Restore channel from the provided channel id string. __Minimum server version__: 3.10 ##### Permissions `manage_team` permission for the team of the channel. operationId: RestoreChannel parameters: - name: channel_id in: path description: Channel GUID required: true schema: type: string responses: "200": description: Channel restore successful content: application/json: schema: $ref: "#/components/schemas/Channel" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "/api/v4/channels/{channel_id}/move": post: tags: - channels summary: Move a channel description: | Move a channel to another team. __Minimum server version__: 5.26 ##### Permissions Must have `manage_system` permission. operationId: MoveChannel parameters: - name: channel_id in: path description: Channel GUID required: true schema: type: string requestBody: content: application/json: schema: type: object required: - team_id properties: team_id: type: string force: description: "Remove members those are not member of target team before moving the channel." type: boolean required: true responses: "200": description: Channel move successful content: application/json: schema: $ref: "#/components/schemas/Channel" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "/api/v4/channels/{channel_id}/stats": get: tags: - channels summary: Get channel statistics description: | Get statistics for a channel. ##### Permissions Must have the `read_channel` permission. operationId: GetChannelStats parameters: - name: channel_id in: path description: Channel GUID required: true schema: type: string responses: "200": description: Channel statistics retrieval successful content: application/json: schema: $ref: "#/components/schemas/ChannelStats" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "/api/v4/channels/{channel_id}/pinned": get: tags: - channels summary: Get a channel's pinned posts description: Get a list of pinned posts for channel. operationId: GetPinnedPosts parameters: - name: channel_id in: path description: Channel GUID required: true schema: type: string responses: "200": description: The list of channel pinned posts content: application/json: schema: $ref: "#/components/schemas/PostList" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "/api/v4/teams/{team_id}/channels": get: tags: - channels summary: Get public channels description: > Get a page of public channels on a team based on query string parameters - page and per_page. ##### Permissions Must be authenticated and have the `list_team_channels` permission. operationId: GetPublicChannelsForTeam parameters: - name: team_id in: path description: Team GUID required: true schema: type: string - name: page in: query description: The page to select. schema: type: integer default: 0 - name: per_page in: query description: The number of public channels per page. schema: type: integer default: 60 responses: "200": description: Channels retrieval successful content: application/json: schema: type: array items: $ref: "#/components/schemas/Channel" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "/api/v4/teams/{team_id}/channels/private": get: tags: - channels summary: Get private channels description: | Get a page of private channels on a team based on query string parameters - team_id, page and per_page. __Minimum server version__: 5.26 ##### Permissions Must have `manage_system` permission. operationId: GetPrivateChannelsForTeam parameters: - name: team_id in: path description: Team GUID required: true schema: type: string - name: page in: query description: The page to select. schema: type: integer default: 0 - name: per_page in: query description: The number of private channels per page. schema: type: integer default: 60 responses: "200": description: Channels retrieval successful content: application/json: schema: type: array items: $ref: "#/components/schemas/Channel" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "/api/v4/teams/{team_id}/channels/recommended": get: tags: - channels summary: Get recommended public channels for the current user description: | Return the public channels on a team that have a membership policy assigned, where the requesting user's attributes match to the policy. Membership policies on public channels are advisory: anyone can still join these channels. This endpoint surfaces them as "Recommended channels" for the requester. Returns an empty list if the Enterprise Advanced license is not active, if `AccessControlSettings.EnableAttributeBasedAccessControl` is `false`, or if the user's attributes do not match any active public-channel policy in the team. __Minimum server version__: 11.8 ##### Permissions Must be authenticated and have `list_team_channels` on the team. operationId: GetRecommendedChannelsForTeam parameters: - name: team_id in: path description: Team GUID required: true schema: type: string responses: "200": description: Recommended channels retrieval successful content: application/json: schema: type: array items: $ref: "#/components/schemas/Channel" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "/api/v4/teams/{team_id}/channels/deleted": get: tags: - channels summary: Get deleted channels description: > Get a page of deleted channels on a team based on query string parameters - team_id, page and per_page. __Minimum server version__: 3.10 operationId: GetDeletedChannelsForTeam parameters: - name: team_id in: path description: Team GUID required: true schema: type: string - name: page in: query description: The page to select. schema: type: integer default: 0 - name: per_page in: query description: The number of public channels per page. schema: type: integer default: 60 responses: "200": description: Channels retrieval successful content: application/json: schema: type: array items: $ref: "#/components/schemas/Channel" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "/api/v4/teams/{team_id}/channels/autocomplete": get: tags: - channels summary: Autocomplete channels description: > Autocomplete public channels on a team based on the search term provided in the request URL. __Minimum server version__: 4.7 ##### Permissions Must have the `list_team_channels` permission. operationId: AutocompleteChannelsForTeam parameters: - name: team_id in: path description: Team GUID required: true schema: type: string - name: name in: query description: Name or display name required: true schema: type: string responses: "200": description: Channels autocomplete successful content: application/json: schema: type: array items: $ref: "#/components/schemas/Channel" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "/api/v4/teams/{team_id}/channels/search_autocomplete": get: tags: - channels summary: Autocomplete channels for search description: > Autocomplete your channels on a team based on the search term provided in the request URL. __Minimum server version__: 5.4 ##### Permissions Must have the `list_team_channels` permission. operationId: AutocompleteChannelsForTeamForSearch parameters: - name: team_id in: path description: Team GUID required: true schema: type: string - name: name in: query description: Name or display name required: true schema: type: string responses: "200": description: Channels autocomplete successful content: application/json: schema: type: array items: $ref: "#/components/schemas/Channel" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "/api/v4/teams/{team_id}/channels/managed_categories": get: tags: - channels summary: Get managed category mappings description: > Returns a map of channel ID to managed category name for all channels the requesting user is a member of in the given team that have a managed category assigned. Requires an Enterprise license and the `ManagedChannelCategories` feature flag to be enabled. ##### Permissions Must be authenticated. operationId: GetManagedCategories parameters: - name: team_id in: path description: Team ID required: true schema: type: string responses: "200": description: Managed category mappings retrieved successfully content: application/json: schema: type: object additionalProperties: type: string description: A map of channel ID to managed category name "401": $ref: "#/components/responses/Unauthorized" "404": description: Returned when the `ManagedChannelCategories` feature flag is disabled. "501": description: Returned when the server does not have an Enterprise license. "/api/v4/teams/{team_id}/channels/search": post: tags: - channels summary: Search channels description: > Search public channels on a team based on the search term provided in the request body. ##### Permissions Must have the `list_team_channels` permission. In server version 5.16 and later, a user without the `list_team_channels` permission will be able to use this endpoint, with the search results limited to the channels that the user is a member of. operationId: SearchChannels parameters: - name: team_id in: path description: Team GUID required: true schema: type: string requestBody: content: application/json: schema: type: object required: - term properties: term: description: The search term to match against the name or display name of channels type: string description: Search criteria required: true responses: "201": description: Channels search successful content: application/json: schema: type: array items: $ref: "#/components/schemas/Channel" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "/api/v4/teams/{team_id}/channels/name/{channel_name}": get: tags: - channels summary: Get a channel by name description: | Gets channel from the provided team id and channel name strings. ##### Permissions `read_channel` permission for the channel. operationId: GetChannelByName parameters: - name: team_id in: path description: Team GUID required: true schema: type: string - name: channel_name in: path description: Channel Name required: true schema: type: string - name: include_deleted in: query description: Defines if deleted channels should be returned or not (Mattermost Server 5.26.0+) schema: type: boolean default: false responses: "200": description: Channel retrieval successful content: application/json: schema: $ref: "#/components/schemas/Channel" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "/api/v4/teams/name/{team_name}/channels/name/{channel_name}": get: tags: - channels summary: Get a channel by name and team name description: | Gets a channel from the provided team name and channel name strings. ##### Permissions `read_channel` permission for the channel. operationId: GetChannelByNameForTeamName parameters: - name: team_name in: path description: Team Name required: true schema: type: string - name: channel_name in: path description: Channel Name required: true schema: type: string - name: include_deleted in: query description: Defines if deleted channels should be returned or not (Mattermost Server 5.26.0+) schema: type: boolean default: false responses: "200": description: Channel retrieval successful content: application/json: schema: $ref: "#/components/schemas/Channel" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "/api/v4/channels/{channel_id}/members": get: tags: - channels summary: Get channel members description: | Get a page of members for a channel. ##### Permissions `read_channel` permission for the channel. operationId: GetChannelMembers parameters: - name: channel_id in: path description: Channel GUID required: true schema: type: string - name: page in: query description: The page to select. schema: type: integer default: 0 - name: per_page in: query description: The number of members per page. schema: type: integer default: 60 responses: "200": description: Channel members retrieval successful content: application/json: schema: type: array items: $ref: "#/components/schemas/ChannelMember" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" post: tags: - channels summary: Add user(s) to channel description: Add a user(s) to a channel by creating a channel member object(s). operationId: AddChannelMember parameters: - name: channel_id in: path description: The channel ID required: true schema: type: string requestBody: content: application/json: schema: type: object properties: user_id: type: string description: The ID of user to add into the channel, for backwards compatibility. user_ids: type: array items: type: string minItems: 1 maxItems: 1000 description: The IDs of users to add into the channel, required if 'user_id' doess not exist. post_root_id: type: string description: The ID of root post where link to add channel member originates required: true responses: "201": description: Channel member creation successful content: application/json: schema: $ref: "#/components/schemas/ChannelMember" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" put: tags: - channels summary: Set channel members description: | Set the complete membership list for a channel, with optional channel admin designation. The server compares the provided list against the current membership and adds or removes users as needed. Users already in the channel are left untouched (no-op). When `channel_admins` is provided, a role reconciliation phase runs after membership changes: listed users are promoted to channel admin, all other members are demoted. When `channel_admins` is omitted (null), existing admin roles are preserved. Results are streamed back as NDJSON (`application/x-ndjson`), one line per batch. Each line is a JSON object with `added`, `removed`, `promoted`, `demoted`, and `errors` arrays for that batch. Removals are processed before additions, then role changes. Private channels cannot be emptied entirely. DM/GM and group-constrained channels are rejected. #### Example: membership only Request (using `batch_size=2` and `batch_delay_ms=200`): ```bash curl -X PUT \ 'https://mattermost.example.com/api/v4/channels/channel123/members?batch_size=2&batch_delay_ms=200' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{"members": ["user_id_1", "user_id_2", "user_id_3", "user_id_4"]}' ``` Streamed NDJSON response (one JSON object per line, one line per batch): ```text {"added":[],"removed":["user_id_5","user_id_6"],"errors":[]} {"added":["user_id_3","user_id_4"],"removed":[],"errors":[]} {"added":[],"removed":[],"errors":[{"user_id":"user_id_7","id":"api.channel.add_members.user_denied","error":"user is not a member of the team"}]} ``` In this example, `user_id_1` and `user_id_2` were already members (no-op), `user_id_5` and `user_id_6` were removed, `user_id_3` and `user_id_4` were added, and `user_id_7` could not be added because the user is not on the team. #### Example: membership with admin roles ```bash curl -X PUT \ 'https://mattermost.example.com/api/v4/channels/channel123/members' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{"members": ["user_id_1", "user_id_2", "user_id_3"], "channel_admins": ["user_id_1"]}' ``` Response: ```text {"added":["user_id_3"],"removed":["user_id_4"]} {"promoted":["user_id_1"],"demoted":["user_id_2"]} ``` In this example, `user_id_1` was promoted to channel admin and `user_id_2` was demoted. When `channel_admins` is omitted, existing admin roles are preserved. __Minimum server version__: 11.7 ##### Permissions Must have `manage_system` permission (system admin only). operationId: SetChannelMembers parameters: - name: channel_id in: path description: Channel GUID required: true schema: type: string - name: batch_size in: query description: Number of add/remove operations per batch. schema: type: integer default: 100 minimum: 1 maximum: 1000 - name: batch_delay_ms in: query description: Milliseconds to pause between batches, giving the server time to process websocket events and plugin hooks. schema: type: integer default: 500 minimum: 0 maximum: 10000 requestBody: description: JSON object specifying the complete desired membership and optional channel admin designations. Request body is limited to 12 MB. content: application/json: schema: type: object required: - members properties: members: type: array items: type: string description: User IDs for the desired channel membership. The final membership is the union of `members` and `channel_admins`. channel_admins: type: array nullable: true items: type: string description: User IDs that should have the channel admin role. Users listed here are automatically included in the desired membership (they do not need to also appear in `members`). When null or omitted, existing admin roles are preserved for members who remain in the channel. When present (including empty array), admin roles are set declaratively. required: true responses: "200": description: | Streamed NDJSON response. Each line is a JSON object representing one batch of results. If the operation is interrupted (e.g. context cancellation), a final NDJSON line with an `error` field is emitted so the client can distinguish partial from full success: `{"error":"The set channel members operation was cancelled."}` content: application/x-ndjson: schema: oneOf: - type: object description: A batch of results from the set channel members operation. properties: added: type: array items: type: string description: User IDs successfully added to the channel in this batch. removed: type: array items: type: string description: User IDs successfully removed from the channel in this batch. promoted: type: array items: type: string description: User IDs promoted to channel admin in this batch. demoted: type: array items: type: string description: User IDs demoted from channel admin in this batch. errors: type: array items: type: object properties: user_id: type: string description: The user ID that failed. id: type: string description: Machine-readable error identifier (i18n key). error: type: string description: Human-readable description of the failure. description: Per-user failures (not on team, deleted user, cannot remove from default channel, plugin rejection). - type: object description: Terminal error line emitted when the operation is interrupted. required: - error properties: error: type: string description: Human-readable description of the interruption. "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "/api/v4/channels/{channel_id}/members/ids": post: tags: - channels summary: Get channel members by ids description: | Get a list of channel members based on the provided user ids. ##### Permissions Must have the `read_channel` permission. operationId: GetChannelMembersByIds parameters: - name: channel_id in: path description: Channel GUID required: true schema: type: string requestBody: content: application/json: schema: type: array items: type: string description: List of user ids. required: true responses: "200": description: Channel member list retrieval successful content: application/json: schema: type: array items: $ref: "#/components/schemas/ChannelMember" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "/api/v4/channels/{channel_id}/members/{user_id}": get: tags: - channels summary: Get channel member description: | Get a channel member. ##### Permissions `read_channel` permission for the channel. operationId: GetChannelMember parameters: - name: channel_id in: path description: Channel GUID required: true schema: type: string - name: user_id in: path description: User GUID required: true schema: type: string responses: "200": description: Channel member retrieval successful content: application/json: schema: $ref: "#/components/schemas/ChannelMember" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" delete: tags: - channels summary: Remove user from channel description: > Delete a channel member, effectively removing them from a channel. In server version 5.3 and later, channel members can only be deleted from public or private channels. ##### Permissions `manage_public_channel_members` permission if the channel is public. `manage_private_channel_members` permission if the channel is private. operationId: RemoveUserFromChannel parameters: - name: channel_id in: path description: Channel GUID required: true schema: type: string - name: user_id in: path description: User GUID required: true schema: type: string responses: "200": description: Channel member deletion successful content: application/json: schema: $ref: "#/components/schemas/StatusOK" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "/api/v4/channels/{channel_id}/members/{user_id}/roles": put: tags: - channels summary: Update channel roles description: | Update a user's roles for a channel. ##### Permissions Must have `manage_channel_roles` permission for the channel. operationId: UpdateChannelRoles parameters: - name: channel_id in: path description: Channel GUID required: true schema: type: string - name: user_id in: path description: User GUID required: true schema: type: string requestBody: content: application/json: schema: type: object required: - roles properties: roles: type: string description: Space-delimited channel roles to assign to the user required: true responses: "200": description: Channel roles update successful content: application/json: schema: $ref: "#/components/schemas/StatusOK" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "/api/v4/channels/{channel_id}/members/{user_id}/schemeRoles": put: tags: - channels summary: Update the scheme-derived roles of a channel member. description: > Update a channel member's scheme_admin/scheme_user properties. Typically this should either be `scheme_admin=false, scheme_user=true` for ordinary channel member, or `scheme_admin=true, scheme_user=true` for a channel admin. __Minimum server version__: 5.0 ##### Permissions Must be authenticated and have the `manage_channel_roles` permission. operationId: UpdateChannelMemberSchemeRoles parameters: - name: channel_id in: path description: Channel GUID required: true schema: type: string - name: user_id in: path description: User GUID required: true schema: type: string requestBody: content: application/json: schema: type: object required: - scheme_admin - scheme_user properties: scheme_admin: type: boolean scheme_user: type: boolean description: Scheme properties. required: true responses: "200": description: Channel member's scheme-derived roles updated successfully. content: application/json: schema: $ref: "#/components/schemas/StatusOK" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "/api/v4/channels/{channel_id}/members/{user_id}/notify_props": put: tags: - channels summary: Update channel notifications description: > Update a user's notification properties for a channel. Only the provided fields are updated. ##### Permissions Must be logged in as the user or have `edit_other_users` permission. operationId: UpdateChannelNotifyProps parameters: - name: channel_id in: path description: Channel GUID required: true schema: type: string - name: user_id in: path description: User GUID required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/ChannelNotifyProps" required: true responses: "200": description: Channel notification properties update successful content: application/json: schema: $ref: "#/components/schemas/StatusOK" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "/api/v4/channels/{channel_id}/members/{user_id}/autotranslation": put: tags: - channels summary: Update channel member autotranslation setting description: > Update a user's autotranslation setting for a channel. This controls whether messages in the channel should not be automatically translated for the user. By default, autotranslations are enabled for all users if the channel is enabled for autotranslation. ##### Permissions Must be logged in as the user or have `edit_other_users` permission. operationId: UpdateChannelMemberAutotranslation parameters: - name: channel_id in: path description: Channel GUID required: true schema: type: string - name: user_id in: path description: User GUID required: true schema: type: string requestBody: content: application/json: schema: type: object required: - autotranslation_disabled properties: autotranslation_disabled: type: boolean description: Whether to disable autotranslation for the user in this channel required: true responses: "200": description: Channel member autotranslation setting update successful content: application/json: schema: $ref: "#/components/schemas/StatusOK" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "/api/v4/channels/members/{user_id}/mark_read": post: tags: - channels summary: Mark multiple channels as read description: | Mark multiple channels as viewed for the given user. ##### Permissions Must be logged in as the user or have `edit_other_users` permission. operationId: MarkChannelsReadForUser parameters: - in: path name: user_id description: User ID to mark channels read for required: true schema: type: string requestBody: content: application/json: schema: type: array items: type: string required: true responses: "200": description: Channels marked as read content: application/json: schema: type: object properties: status: type: string last_viewed_at_times: type: object "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "/api/v4/channels/stats/member_count": post: tags: - channels summary: Get member counts for multiple channels description: | Get channel member counts for a list of channel IDs. ##### Permissions Must have access to member count for all requested channels. operationId: GetChannelsMemberCount requestBody: content: application/json: schema: type: array items: type: string required: true responses: "200": description: Channel member counts retrieval successful content: application/json: schema: type: object additionalProperties: type: integer format: int64 "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "/api/v4/channels/members/{user_id}/view": post: tags: - channels summary: View channel description: > Perform all the actions involved in viewing a channel. This includes marking channels as read, clearing push notifications, and updating the active channel. ##### Permissions Must be logged in as user or have `edit_other_users` permission. __Response only includes `last_viewed_at_times` in Mattermost server 4.3 and newer.__ operationId: ViewChannel parameters: - in: path name: user_id description: User ID to perform the view action for required: true schema: type: string requestBody: content: application/json: schema: type: object required: - channel_id properties: channel_id: type: string description: The channel ID that is being viewed. Use a blank string to indicate that all channels have lost focus. prev_channel_id: type: string description: The channel ID of the previous channel, used when switching channels. Providing this ID will cause push notifications to clear on the channel being switched to. description: Paremeters affecting how and which channels to view required: true responses: "200": description: Channel view successful content: application/json: schema: type: object properties: status: type: string description: Value should be "OK" if successful last_viewed_at_times: type: object description: A JSON object mapping channel IDs to the channel view times "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "/api/v4/channels/members/{user_id}/direct/read": put: tags: - channels summary: Mark all direct and group messages as read description: | Mark all direct and group messages as read for a user. ##### Permissions Must be logged in as user or have `edit_other_users` permission. __Minimum server version__: 11.3 operationId: MarkAllDirectMessagesRead parameters: - in: path name: user_id description: User ID to mark messages as read for required: true schema: type: string responses: "200": description: Direct messages marked as read successfully content: application/json: schema: type: object properties: status: type: string description: Value should be "OK" if successful last_viewed_at_times: type: object description: A JSON object mapping channel IDs to the last viewed times additionalProperties: type: integer format: int64 "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "501": $ref: "#/components/responses/NotImplemented" "/api/v4/users/{user_id}/teams/{team_id}/channels/members": get: tags: - channels summary: Get channel memberships and roles for a user description: > Get all channel memberships and associated membership roles (i.e. `channel_user`, `channel_admin`) for a user on a specific team. ##### Permissions Logged in as the user and `view_team` permission for the team. Having `manage_system` permission voids the previous requirements. operationId: GetChannelMembersForUser parameters: - name: user_id in: path description: User GUID required: true schema: type: string - name: team_id in: path description: Team GUID required: true schema: type: string responses: "200": description: Channel members retrieval successful content: application/json: schema: type: array items: $ref: "#/components/schemas/ChannelMember" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "/api/v4/users/{user_id}/teams/{team_id}/channels": get: tags: - channels summary: Get channels for user description: > Get all the channels on a team for a user. ##### Permissions Logged in as the user, or have `edit_other_users` permission, and `view_team` permission for the team. operationId: GetChannelsForTeamForUser parameters: - name: user_id in: path description: User GUID required: true schema: type: string - name: team_id in: path description: Team GUID required: true schema: type: string - name: include_deleted in: query description: Defines if deleted channels should be returned or not schema: type: boolean default: false - name: last_delete_at in: query description: Filters the deleted channels by this time in epoch format. Does not have any effect if include_deleted is set to false. schema: type: integer default: 0 responses: "200": description: Channels retrieval successful content: application/json: schema: type: array items: $ref: "#/components/schemas/Channel" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "/api/v4/users/{user_id}/channels": get: tags: - channels summary: Get all channels from all teams description: | Get all channels from all teams that a user is a member of. __Minimum server version__: 6.1 ##### Permissions Logged in as the user, or have `edit_other_users` permission. operationId: GetChannelsForUser parameters: - name: user_id in: path description: The ID of the user. This can also be "me" which will point to the current user. required: true schema: type: string - name: last_delete_at in: query description: Filters the deleted channels by this time in epoch format. Does not have any effect if include_deleted is set to false. schema: type: integer default: 0 - name: include_deleted in: query description: Defines if deleted channels should be returned or not schema: type: boolean default: false responses: "200": description: Channels retrieval successful content: application/json: schema: type: array items: $ref: "#/components/schemas/Channel" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "/api/v4/users/{user_id}/channels/{channel_id}/unread": get: tags: - channels summary: Get unread messages description: > Get the total unread messages and mentions for a channel for a user. ##### Permissions Must be logged in as user and have the `read_channel` permission, or have `edit_other_usrs` permission. operationId: GetChannelUnread parameters: - name: user_id in: path description: User GUID required: true schema: type: string - name: channel_id in: path description: Channel GUID required: true schema: type: string responses: "200": description: Channel unreads retrieval successful content: application/json: schema: $ref: "#/components/schemas/ChannelUnread" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "/api/v4/channels/{channel_id}/scheme": put: tags: - channels summary: Set a channel's scheme description: > Set a channel's scheme, more specifically sets the scheme_id value of a channel record. ##### Permissions Must have `manage_system` permission. __Minimum server version__: 4.10 operationId: UpdateChannelScheme parameters: - name: channel_id in: path description: Channel GUID required: true schema: type: string requestBody: content: application/json: schema: type: object required: - scheme_id properties: scheme_id: type: string description: The ID of the scheme. description: Scheme GUID required: true responses: "200": description: Update channel scheme successful content: application/json: schema: $ref: "#/components/schemas/StatusOK" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "501": $ref: "#/components/responses/NotImplemented" "/api/v4/channels/{channel_id}/members_minus_group_members": get: tags: - channels summary: Channel members minus group members. description: > Get the set of users who are members of the channel minus the set of users who are members of the given groups. Each user object contains an array of group objects representing the group memberships for that user. Each user object contains the boolean fields `scheme_guest`, `scheme_user`, and `scheme_admin` representing the roles that user has for the given channel. ##### Permissions Must have `manage_system` permission. __Minimum server version__: 5.14 operationId: ChannelMembersMinusGroupMembers parameters: - name: channel_id in: path description: Channel GUID required: true schema: type: string - name: group_ids in: query description: A comma-separated list of group ids. required: true schema: type: string default: "" - name: page in: query description: The page to select. schema: type: integer default: 0 - name: per_page in: query description: The number of users per page. schema: type: integer default: 0 responses: "200": description: Successfully returns users specified by the pagination, and the total_count. "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "/api/v4/channels/{channel_id}/member_counts_by_group": get: tags: - channels summary: Channel members counts for each group that has atleast one member in the channel description: > Returns a set of ChannelMemberCountByGroup objects which contain a `group_id`, `channel_member_count` and a `channel_member_timezones_count`. ##### Permissions Must have `read_channel` permission for the given channel. __Minimum server version__: 5.24 operationId: GetChannelMemberCountsByGroup parameters: - name: channel_id in: path description: Channel GUID required: true schema: type: string - name: include_timezones in: query description: Defines if member timezone counts should be returned or not schema: type: boolean default: false responses: "200": description: Successfully returns member counts by group for the given channel. "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "/api/v4/channels/{channel_id}/moderations": get: tags: - channels summary: Get information about channel's moderation. description: > ##### Permissions Must have `manage_system` permission. __Minimum server version__: 5.22 operationId: GetChannelModerations parameters: - name: channel_id in: path description: Channel GUID required: true schema: type: string responses: "200": description: "Retreived successfully" content: application/json: schema: type: array items: $ref: "#/components/schemas/ChannelModeration" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "/api/v4/channels/{channel_id}/moderations/patch": put: tags: - channels summary: Update a channel's moderation settings. description: > ##### Permissions Must have `manage_system` permission. __Minimum server version__: 5.22 operationId: PatchChannelModerations requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ChannelModerationPatch" parameters: - name: channel_id in: path description: Channel GUID required: true schema: type: string responses: "200": description: "Patched successfully" content: application/json: schema: type: array items: $ref: "#/components/schemas/ChannelModeration" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "/api/v4/users/{user_id}/teams/{team_id}/channels/categories": get: tags: - channels summary: Get user's sidebar categories description: > Get a list of sidebar categories that will appear in the user's sidebar on the given team, including a list of channel IDs in each category. __Minimum server version__: 5.26 ##### Permissions Must be authenticated and have the `list_team_channels` permission. operationId: GetSidebarCategoriesForTeamForUser parameters: - name: team_id in: path description: Team GUID required: true schema: type: string - name: user_id in: path description: User GUID required: true schema: type: string responses: "200": description: Category retrieval successful content: application/json: schema: type: array items: $ref: "#/components/schemas/OrderedSidebarCategories" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" post: tags: - channels summary: Create user's sidebar category description: > Create a custom sidebar category for the user on the given team. __Minimum server version__: 5.26 ##### Permissions Must be authenticated and have the `list_team_channels` permission. operationId: CreateSidebarCategoryForTeamForUser parameters: - name: team_id in: path description: Team GUID required: true schema: type: string - name: user_id in: path description: User GUID required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/SidebarCategory" required: true responses: "200": description: Category creation successful content: application/json: schema: $ref: "#/components/schemas/SidebarCategory" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" put: tags: - channels summary: Update user's sidebar categories description: > Update any number of sidebar categories for the user on the given team. This can be used to reorder the channels in these categories. __Minimum server version__: 5.26 ##### Permissions Must be authenticated and have the `list_team_channels` permission. operationId: UpdateSidebarCategoriesForTeamForUser parameters: - name: team_id in: path description: Team GUID required: true schema: type: string - name: user_id in: path description: User GUID required: true schema: type: string requestBody: content: application/json: schema: type: array items: $ref: "#/components/schemas/SidebarCategory" required: true responses: "200": description: Category update successful content: application/json: schema: $ref: "#/components/schemas/SidebarCategory" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "/api/v4/users/{user_id}/teams/{team_id}/channels/categories/order": get: tags: - channels summary: Get user's sidebar category order description: > Returns the order of the sidebar categories for a user on the given team as an array of IDs. __Minimum server version__: 5.26 ##### Permissions Must be authenticated and have the `list_team_channels` permission. operationId: GetSidebarCategoryOrderForTeamForUser parameters: - name: team_id in: path description: Team GUID required: true schema: type: string - name: user_id in: path description: User GUID required: true schema: type: string responses: "200": description: Order retrieval successful content: application/json: schema: type: array items: type: string "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" put: tags: - channels summary: Update user's sidebar category order description: > Updates the order of the sidebar categories for a user on the given team. The provided array must include the IDs of all categories on the team. __Minimum server version__: 5.26 ##### Permissions Must be authenticated and have the `list_team_channels` permission. operationId: UpdateSidebarCategoryOrderForTeamForUser parameters: - name: team_id in: path description: Team GUID required: true schema: type: string - name: user_id in: path description: User GUID required: true schema: type: string requestBody: content: application/json: schema: type: array items: type: string required: true responses: "200": description: Order update successful content: application/json: schema: type: array items: type: string "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "/api/v4/users/{user_id}/teams/{team_id}/channels/categories/{category_id}": get: tags: - channels summary: Get sidebar category description: > Returns a single sidebar category for the user on the given team. __Minimum server version__: 5.26 ##### Permissions Must be authenticated and have the `list_team_channels` permission. operationId: GetSidebarCategoryForTeamForUser parameters: - name: team_id in: path description: Team GUID required: true schema: type: string - name: user_id in: path description: User GUID required: true schema: type: string - name: category_id in: path description: Category GUID required: true schema: type: string responses: "200": description: Category retrieval successful content: application/json: schema: $ref: "#/components/schemas/SidebarCategory" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" put: tags: - channels summary: Update sidebar category description: > Updates a single sidebar category for the user on the given team. __Minimum server version__: 5.26 ##### Permissions Must be authenticated and have the `list_team_channels` permission. operationId: UpdateSidebarCategoryForTeamForUser parameters: - name: team_id in: path description: Team GUID required: true schema: type: string - name: user_id in: path description: User GUID required: true schema: type: string - name: category_id in: path description: Category GUID required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/SidebarCategory" required: true responses: "200": description: Category update successful content: application/json: schema: $ref: "#/components/schemas/SidebarCategory" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" delete: tags: - channels summary: Delete sidebar category description: > Deletes a single sidebar category for the user on the given team. Only custom categories can be deleted. __Minimum server version__: 5.26 ##### Permissions Must be authenticated and have the `list_team_channels` permission. operationId: RemoveSidebarCategoryForTeamForUser parameters: - name: team_id in: path description: Team GUID required: true schema: type: string - name: user_id in: path description: User GUID required: true schema: type: string - name: category_id in: path description: Category GUID required: true schema: type: string responses: "200": description: Category delete successful content: application/json: schema: $ref: "#/components/schemas/SidebarCategory" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "/api/v4/channels/{channel_id}/common_teams": get: tags: - channels - group message summary: Get common teams for members of a Group Message. description: | Gets all the common teams for all active members of a Group Message channel. Returns empty list of no common teams are found. __Minimum server version__: 9.1 ##### Permissions Must be authenticated and have the `read_channel` permission for the channel. operationId: GetGroupMessageMembersCommonTeams parameters: - name: channel_id in: path description: Channel GUID required: true schema: type: string responses: "200": description: Common teams retrieval successful content: application/json: schema: type: array items: $ref: "#/components/schemas/Team" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "/api/v4/channels/{channel_id}/convert_to_channel": post: tags: - channels - group message summary: Convert group message to private channel description: | Converts a group message channel into a private channel in the specified team. ##### Permissions Must have `create_private_channel` permission in the destination team. operationId: ConvertGroupMessageToChannel parameters: - name: channel_id in: path description: Group message channel ID required: true schema: type: string requestBody: required: true content: application/json: schema: type: object required: - channel_id - team_id properties: channel_id: type: string team_id: type: string responses: "200": description: Conversion successful content: application/json: schema: $ref: "#/components/schemas/Channel" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound"