mirror of
https://github.com/mattermost/mattermost.git
synced 2026-08-26 21:27:40 -05:00
Doug Lauder
9fa8c8c0c8
* Add bulk set (replace) channel memberships API
PUT /api/v4/channels/{channel_id}/members accepts a complete desired
membership list and reconciles it against the current state, adding
missing users and removing extras while leaving existing members
untouched. Results stream back as NDJSON with configurable batch size
and delay to manage server load. Sysadmin only. Private channels
cannot be emptied entirely.
2861 lines
90 KiB
YAML
2861 lines
90 KiB
YAML
/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 `EnableManagedChannelCategories`
|
|
config setting to be enabled.
|
|
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 `EnableManagedChannelCategories` config setting to be enabled.
|
|
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/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 `EnableManagedChannelCategories`
|
|
config setting 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"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"/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 <token>' \
|
|
-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 <token>' \
|
|
-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}/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/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/sharedchannels/{channel_id}/remotes":
|
|
get:
|
|
tags:
|
|
- channels
|
|
summary: Get remote clusters for a shared channel
|
|
description: |
|
|
Gets the remote clusters information for a shared channel.
|
|
|
|
__Minimum server version__: 10.10
|
|
|
|
##### Permissions
|
|
Must be authenticated and have the `read_channel` permission for the channel.
|
|
operationId: GetSharedChannelRemotes
|
|
parameters:
|
|
- name: channel_id
|
|
in: path
|
|
description: Channel GUID
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
description: Remote clusters retrieval successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/RemoteClusterInfo"
|
|
"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"
|