openapi: 3.0.0 info: description: | There is also a work-in-progress [Postman API reference](https://documenter.getpostman.com/view/4508214/RW8FERUn). version: 4.0.0 title: Mattermost API Reference termsOfService: https://about.mattermost.com/default-terms/ contact: email: feedback@mattermost.com x-logo: url: https://mattermost.com/wp-content/uploads/2022/02/logoHorizontal.png backgroundColor: '#FFFFFF' tags: - name: introduction description: | The Mattermost Web Services API is used by Mattermost clients and third party applications to interact with the server. [JavaScript and Golang drivers for](/#tag/drivers) connecting to the APIs are also available. ### Support Mattermost core committers work with the community to keep the API documentation up-to-date. If you have questions on API routes not listed in this reference, please [join the Mattermost community server](https://community.mattermost.com) to ask questions in the Developers channel, [or post questions to our Developer Discussion forum](https://forum.mattermost.org/c/dev). [Bug reports](https://github.com/mattermost/mattermost/issues) in the documentation or the API are also welcome, as are pull requests to fix the issues. ### Contributing When you have answers to API questions not addressed in our documentation we ask you to consider making a pull request to improve our reference. Small and large changes are all welcome. We also have [Help Wanted tickets](https://github.com/mattermost/mattermost/issues?q=is%3Aopen+is%3Aissue+label%3AArea%2FAPI) available for community members who would like to help others more easily use the APIs. We acknowledge everyone's contribution in the [release notes of our next version](https://docs.mattermost.com/administration/changelog.html#contributors). The source code for this API reference is hosted at https://github.com/mattermost/mattermost/tree/master/api. - name: schema description: | All API access is through HTTP(S) requests at `your-mattermost-url.com/api/v4`. All request and response bodies are `application/json`. When using endpoints that require a user id, the string `me` can be used in place of the user id to indicate the action is to be taken for the logged in user. - name: drivers description: | The easiest way to interact with the Mattermost Web Service API is through a language specific driver. #### Official Drivers * Mattermost JavaScript/TypeScript Driver * [NPM](https://www.npmjs.com/package/@mattermost/client) * [Source](https://github.com/mattermost/mattermost/tree/master/webapp/platform/client) * [Mattermost Golang Driver](https://pkg.go.dev/github.com/mattermost/mattermost/server/public/model#Client4) #### Community-built Drivers For community-built drivers and API wrappers, see [our app directory](https://mattermost.com/marketplace/). - name: authentication description: | There are multiple ways to authenticate against the Mattermost API. All examples assume there is a Mattermost instance running at http://localhost:8065. #### Session Token Make an HTTP POST to `your-mattermost-url.com/api/v4/users/login` with a JSON body indicating the user’s `login_id`, `password` and optionally the MFA `token`. The `login_id` can be an email, username or an AD/LDAP ID depending on the system's configuration. ``` curl -i -d '{"login_id":"someone@nowhere.com","password":"thisisabadpassword"}' http://localhost:8065/api/v4/users/login ``` NOTE: If you're running cURL on windows, you will have to change the single quotes to double quotes, and escape the inner double quotes with backslash, like below: ``` curl -i -d "{\"login_id\":\"someone@nowhere.com\",\"password\":\"thisisabadpassword\"}" http://localhost:8065/api/v4/users/login ``` If successful, the response will contain a `Token` header and a user object in the body. ``` HTTP/1.1 200 OK Set-Cookie: MMSID=hyr5dmb1mbb49c44qmx4whniso; Path=/; Max-Age=2592000; HttpOnly Token: hyr5dmb1mbb49c44qmx4whniso X-Ratelimit-Limit: 10 X-Ratelimit-Remaining: 9 X-Ratelimit-Reset: 1 X-Request-Id: smda55ckcfy89b6tia58shk5fh X-Version-Id: developer Date: Fri, 11 Sep 2015 13:21:14 GMT Content-Length: 657 Content-Type: application/json; charset=utf-8 {{user object as json}} ``` Include the `Token` as part of the `Authorization` header on your future API requests with the `Bearer` method. ``` curl -i -H 'Authorization: Bearer hyr5dmb1mbb49c44qmx4whniso' http://localhost:8065/api/v4/users/me ``` You should now be able to access the API as the user you logged in as. #### Personal Access Tokens Using [personal access tokens](https://docs.mattermost.com/developer/personal-access-tokens.html) is very similar to using a session token. The only real difference is that session tokens will expire, while personal access tokens will live until they are manually revoked by the user or an admin. Just like session tokens, include the personal access token as part of the `Authorization` header in your requests using the `Bearer` method. Assuming our personal access token is `9xuqwrwgstrb3mzrxb83nb357a`, we could use it as shown below. ``` curl -i -H 'Authorization: Bearer 9xuqwrwgstrb3mzrxb83nb357a' http://localhost:8065/api/v4/users/me ``` #### OAuth 2.0 Mattermost has the ability to act as an [OAuth 2.0](https://tools.ietf.org/html/rfc6749) service provider. The official documentation for [using your Mattermost server as an OAuth 2.0 service provider can be found here.](https://docs.mattermost.com/developer/oauth-2-0-applications.html) For an example on how to register an OAuth 2.0 app with your Mattermost instance, please see the [Mattermost-Zapier integration documentation](https://docs.mattermost.com/integrations/zapier.html#register-zapier-as-an-oauth-2-0-application). - name: errors description: | All errors will return an appropriate HTTP response code along with the following JSON body: ``` { "id": "the.error.id", "message": "Something went wrong", // the reason for the error "request_id": "", // the ID of the request "status_code": 0, // the HTTP status code "is_oauth": false // whether the error is OAuth specific } ``` - name: rate limiting description: | Whenever you make an HTTP request to the Mattermost API you might notice the following headers included in the response: ``` X-Ratelimit-Limit: 10 X-Ratelimit-Remaining: 9 X-Ratelimit-Reset: 1441983590 ``` These headers are telling you your current rate limit status. | Header | Description | | ------ | ----------- | | X-Ratelimit-Limit | The maximum number of requests you can make per second. | | X-Ratelimit-Remaining | The number of requests remaining in the current window. | | X-Ratelimit-Reset | The remaining UTC epoch seconds before the rate limit resets. | If you exceed your rate limit for a window you will receive the following error in the body of the response: ``` HTTP/1.1 429 Too Many Requests Date: Tue, 10 Sep 2015 11:20:28 GMT X-RateLimit-Limit: 10 X-RateLimit-Remaining: 0 X-RateLimit-Reset: 1 limit exceeded ``` - name: WebSocket description: | In addition to the HTTP RESTful web service, Mattermost also offers a WebSocket event delivery system and some API functionality. To connect to the WebSocket follow the standard opening handshake as [defined by the RFC specification](https://tools.ietf.org/html/rfc6455#section-1.3) to the `/api/v4/websocket` endpoint of Mattermost. #### Authentication The Mattermost WebSocket can be authenticated using [the standard API authentication methods](/#tag/authentication) (by a cookie or with an explicit Authorization header) or through an authentication challenge. If you're authenticating from a browser and have logged in with the Mattermost API, your authentication cookie should already be set. This is how the Mattermost webapp authenticates with the WebSocket. To authenticate with an authentication challenge, first connect the WebSocket and then send the following JSON over the connection: ``` { "seq": 1, "action": "authentication_challenge", "data": { "token": "mattermosttokengoeshere" } } ``` If successful, you will receive a standard OK response over the WebSocket connection: ``` { "status": "OK", "seq_reply": 1 } ``` Once successfully authenticated, the server will pass a `hello` WebSocket event containing server version over the connection. #### Events WebSocket events are primarily used to alert the client to changes in Mattermost, such as delivering new posts or alerting the client that another user is typing in a channel. Events on the WebSocket will have the form: ``` { "event": "hello", "data": { "server_version": "3.6.0.1451.1c38da627ebb4e3635677db6939e9195" }, "broadcast":{ "omit_users": null, "user_id": "ay5sq51sebfh58ktrce5ijtcwy", "channel_id": "", "team_id": "" }, "seq": 0 } ``` The `event` field indicates the event type, `data` contains any data relevant to the event and `broadcast` contains information about who the event was sent to. For example, the above example has `user_id` set to "ay5sq51sebfh58ktrce5ijtcwy" meaning that only the user with that ID received this event broadcast. The `omit_users` field can contain an array of user IDs that were specifically omitted from receiving the event. The list of Mattermost WebSocket events are: - added_to_team - authentication_challenge - channel_converted - channel_created - channel_deleted - channel_member_updated - channel_updated - channel_viewed - config_changed - delete_team - direct_added - emoji_added - ephemeral_message - group_added - hello - leave_team - license_changed - memberrole_updated - new_user - plugin_disabled - plugin_enabled - plugin_statuses_changed - post_deleted - post_edited - post_unread - posted - preference_changed - preferences_changed - preferences_deleted - reaction_added - reaction_removed - response - role_updated - status_change - typing - update_team - user_added - user_removed - user_role_updated - user_updated - dialog_opened - thread_updated - thread_follow_changed - thread_read_changed #### WebSocket API Mattermost has some basic support for WebSocket APIs. A connected WebSocket can make requests by sending the following over the connection: ``` { "action": "user_typing", "seq": 2, "data": { "channel_id": "nhze199c4j87ped4wannrjdt9c", "parent_id": "" } } ``` This is an example of making a `user_typing` request, with the purpose of alerting the server that the connected client has begun typing in a channel or thread. The `action` field indicates what is being requested, and performs a similar duty as the route in a HTTP API. The `data` field is used to add any additional data along with the request. The server supports binary websocket messages as well in case the client has such a requirement. The `seq` or sequence number is set by the client and should be incremented with every use. It is used to distinguish responses to requests that come down the WebSocket. For example, a standard response to the above request would be: ``` { "status": "OK", "seq_reply": 2 } ``` Notice `seq_reply` is 2, matching the `seq` of the original request. Using this a client can distinguish which request the response is meant for. If there was any information to respond with, it would be encapsulated in a `data` field. In the case of an error, the response would be: ``` { "status": "FAIL", "seq_reply": 2, "error": { "id": "some.error.id.here", "message": "Some error message here" } } ``` The list of WebSocket API actions is: - user_typing - get_statuses - get_statuses_by_ids To see how these actions work, please refer to either the [Golang WebSocket driver](https://github.com/mattermost/mattermost/blob/master/server/public/model/websocket_client.go) or our [JavaScript WebSocket driver](https://github.com/mattermost/mattermost/blob/master/webapp/platform/client/src/websocket.ts). - name: users description: | Endpoints for creating, getting and interacting with users. When using endpoints that require a user id, the string `me` can be used in place of the user id to indicate the action is to be taken for the logged in user. - name: bots description: Endpoints for creating, getting and updating bot users. - name: teams description: Endpoints for creating, getting and interacting with teams. - name: channels description: Endpoints for creating, getting and interacting with channels. - name: posts description: Endpoints for creating, getting and interacting with posts. - name: files description: Endpoints for uploading and interacting with files. - name: uploads description: Endpoints for creating and performing file uploads. - name: bookmarks description: Endpoints for creating, getting and interacting with channel bookmarks. - name: preferences description: Endpoints for saving and modifying user preferences. - name: status description: Endpoints for getting and updating user statuses. - name: emoji description: Endpoints for creating, getting and interacting with emojis. - name: reactions description: Endpoints for creating, getting and removing emoji reactions. - name: webhooks description: Endpoints for creating, getting and updating webhooks. - name: commands description: Endpoints for creating, getting and updating slash commands. - name: system description: General endpoints for interacting with the server, such as configuration and logging. - name: brand description: Endpoints related to custom branding and white-labeling. See [our branding documentation](https://docs.mattermost.com/administration/branding.html) for more information. - name: OAuth description: Endpoints for configuring and interacting with Mattermost as an OAuth 2.0 service provider. - name: SAML description: Endpoints for configuring and interacting with SAML. - name: LDAP description: Endpoints for configuring and interacting with LDAP. - name: groups description: Endpoints related to LDAP groups. - name: compliance description: Endpoints for creating, getting and downloading compliance reports. - name: cluster description: Endpoints for configuring and interacting with high availability clusters. - name: elasticsearch description: Endpoints for configuring and interacting with Elasticsearch. - name: data retention description: Endpoint for getting data retention policy settings. - name: jobs description: Endpoints related to various background jobs that can be run by the server or separately by job servers. - name: plugins description: Endpoints related to uploading and managing plugins. - name: roles description: Endpoints for creating, getting and updating roles. - name: schemes description: Endpoints for creating, getting and updating and deleting schemes. - name: integration_actions description: Endpoints for interactive actions for use by integrations. - name: shared channels description: Endpoints for getting information about shared channels. - name: terms of service description: Endpoints for getting and updating custom terms of service. - name: imports description: Endpoints related to import files. - name: exports description: Endpoints related to export files. - name: Playbooks description: Playbooks - name: PlaybookRuns description: Playbook runs - name: Internal description: Internal endpoints - name: Timeline description: Timeline - name: PlaybookAutofollows description: Playbook Autofollows x-tagGroups: - name: Overview tags: - introduction - schema - name: Standard Features tags: - drivers - authentication - errors - rate limiting - WebSocket - name: Endpoints tags: - users - bots - teams - channels - posts - threads - files - uploads - bookmarks - preferences - status - emoji - reactions - webhooks - commands - system - brand - OAuth - SAML - LDAP - groups - compliance - cluster - cloud - elasticsearch - bleve - data retention - jobs - plugins - roles - schemes - integration_actions - shared channels - terms of service - imports - permissions - exports - usage - name: Playbooks tags: - Playbooks - PlaybookRuns - PlaybookAutofollows - Timeline - Internal servers: - url: http://your-mattermost-url.com - url: https://your-mattermost-url.com paths: /api/v4/users/login: post: tags: - users summary: Login to Mattermost server description: > ##### Permissions No permission required operationId: Login requestBody: content: application/json: schema: type: object properties: id: type: string login_id: type: string token: type: string device_id: type: string ldap_only: type: boolean password: description: The password used for email authentication. type: string description: User authentication object required: true responses: "201": description: User login successful content: application/json: schema: $ref: '#/components/schemas/User' "400": $ref: '#/components/responses/BadRequest' "403": $ref: '#/components/responses/Forbidden' /api/v4/users/login/cws: post: tags: - users summary: Auto-Login to Mattermost server using CWS token description: > CWS stands for Customer Web Server which is the cloud service used to manage cloud instances. ##### Permissions A Cloud license is required operationId: LoginByCwsToken requestBody: content: application/json: schema: type: object properties: login_id: type: string cws_token: type: string description: User authentication object required: true responses: "302": description: Login successful, it'll redirect to login page to perform the autologin "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' /api/v4/users/logout: post: tags: - users summary: Logout from the Mattermost server description: > ##### Permissions An active session is required operationId: Logout responses: "201": description: User logout successful content: application/json: schema: $ref: '#/components/schemas/StatusOK' "400": $ref: '#/components/responses/BadRequest' "403": $ref: '#/components/responses/Forbidden' /api/v4/users: post: tags: - users summary: Create a user description: > Create a new user on the system. Password is required for email login. For other authentication types such as LDAP or SAML, auth_data and auth_service fields are required. ##### Permissions No permission required for creating email/username accounts on an open server. Auth Token is required for other authentication types such as LDAP or SAML. operationId: CreateUser parameters: - name: t in: query description: Token id from an email invitation schema: type: string - name: iid in: query description: Token id from an invitation link schema: type: string requestBody: content: application/json: schema: type: object required: - email - username properties: email: type: string username: type: string first_name: type: string last_name: type: string nickname: type: string auth_data: description: Service-specific authentication data, such as email address. type: string auth_service: description: The authentication service, one of "email", "gitlab", "ldap", "saml", "office365", "google", and "". type: string password: description: The password used for email authentication. type: string locale: type: string props: type: object notify_props: $ref: '#/components/schemas/UserNotifyProps' description: User object to be created required: true responses: "201": description: User creation successful content: application/json: schema: $ref: '#/components/schemas/User' "400": $ref: '#/components/responses/BadRequest' "403": $ref: '#/components/responses/Forbidden' get: tags: - users summary: Get users description: > Get a page of a list of users. Based on query string parameters, select users from a team, channel, or select users not in a specific channel. Since server version 4.0, some basic sorting is available using the `sort` query parameter. Sorting is currently only supported when selecting users on a team. ##### Permissions Requires an active session and (if specified) membership to the channel or team being selected from. operationId: GetUsers parameters: - 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. There is a maximum limit of 200 users per page. schema: type: integer default: 60 - name: in_team in: query description: The ID of the team to get users for. schema: type: string - name: not_in_team in: query description: The ID of the team to exclude users for. Must not be used with "in_team" query parameter. schema: type: string - name: in_channel in: query description: The ID of the channel to get users for. schema: type: string - name: not_in_channel in: query description: The ID of the channel to exclude users for. Must be used with "in_channel" query parameter. schema: type: string - name: in_group in: query description: The ID of the group to get users for. Must have `manage_system` permission. schema: type: string - name: group_constrained in: query description: When used with `not_in_channel` or `not_in_team`, returns only the users that are allowed to join the channel or team based on its group constrains. schema: type: boolean - name: without_team in: query description: Whether or not to list users that are not on any team. This option takes precendence over `in_team`, `in_channel`, and `not_in_channel`. schema: type: boolean - name: active in: query description: Whether or not to list only users that are active. This option cannot be used along with the `inactive` option. schema: type: boolean - name: inactive in: query description: Whether or not to list only users that are deactivated. This option cannot be used along with the `active` option. schema: type: boolean - name: role in: query description: Returns users that have this role. schema: type: string - name: sort in: query description: > Sort is only available in conjunction with certain options below. The paging parameter is also always available. ##### `in_team` Can be "", "last_activity_at" or "create_at". When left blank, sorting is done by username. Note that when "last_activity_at" is specified, an additional "last_activity_at" field will be returned in the response packet. __Minimum server version__: 4.0 ##### `in_channel` Can be "", "status". When left blank, sorting is done by username. `status` will sort by User's current status (Online, Away, DND, Offline), then by Username. __Minimum server version__: 4.7 ##### `in_group` Can be "", "display_name". When left blank, sorting is done by username. `display_name` will sort alphabetically by user's display name. __Minimum server version__: 7.7 schema: type: string - name: roles in: query description: > Comma separated string used to filter users based on any of the specified system roles Example: `?roles=system_admin,system_user` will return users that are either system admins or system users __Minimum server version__: 5.26 schema: type: string - name: channel_roles in: query description: > Comma separated string used to filter users based on any of the specified channel roles, can only be used in conjunction with `in_channel` Example: `?in_channel=4eb6axxw7fg3je5iyasnfudc5y&channel_roles=channel_user` will return users that are only channel users and not admins or guests __Minimum server version__: 5.26 schema: type: string - name: team_roles in: query description: > Comma separated string used to filter users based on any of the specified team roles, can only be used in conjunction with `in_team` Example: `?in_team=4eb6axxw7fg3je5iyasnfudc5y&team_roles=team_user` will return users that are only team users and not admins or guests __Minimum server version__: 5.26 schema: type: string responses: "200": description: User page retrieval successful content: application/json: schema: type: array items: $ref: '#/components/schemas/User' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' x-codeSamples: - lang: Go source: | package main import ( "context" "fmt" "log" "os" "github.com/mattermost/mattermost/server/public/model" ) func main() { client := model.NewAPIv4Client("http://localhost:8065") client.SetToken(os.Getenv("MM_TOKEN")) const perPage = 100 var page int for { users, _, err := client.GetUsers(context.TODO(), page, perPage, "") if err != nil { log.Printf("error fetching users: %v", err) return } for _, u := range users { fmt.Printf("%s\n", u.Username) } if len(users) < perPage { break } page++ } } delete: tags: - users summary: Permanent delete all users description: > Permanently deletes all users and all their related information, including posts. __Minimum server version__: 5.26.0 __Local mode only__: This endpoint is only available through [local mode](https://docs.mattermost.com/administration/mmctl-cli-tool.html#local-mode). operationId: PermanentDeleteAllUsers responses: "200": description: Delete request was successful /api/v4/users/ids: post: tags: - users summary: Get users by ids description: | Get a list of users based on a provided list of user ids. ##### Permissions Requires an active session but no other permissions. operationId: GetUsersByIds parameters: - name: since in: query description: > Only return users that have been modified since the given Unix timestamp (in milliseconds). __Minimum server version__: 5.14 schema: type: integer requestBody: content: application/json: schema: type: array items: type: string description: List of user ids required: true responses: "200": description: User list retrieval successful content: application/json: schema: type: array items: $ref: '#/components/schemas/User' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' /api/v4/users/group_channels: post: tags: - users summary: Get users by group channels ids description: | Get an object containing a key per group channel id in the query and its value as a list of users members of that group channel. The user must be a member of the group ids in the query, or they will be omitted from the response. ##### Permissions Requires an active session but no other permissions. __Minimum server version__: 5.14 operationId: GetUsersByGroupChannelIds requestBody: content: application/json: schema: type: array items: type: string description: List of group channel ids required: true responses: "200": description: User list retrieval successful content: application/json: schema: type: object properties: : type: array items: $ref: '#/components/schemas/User' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' /api/v4/users/usernames: post: tags: - users summary: Get users by usernames description: | Get a list of users based on a provided list of usernames. ##### Permissions Requires an active session but no other permissions. operationId: GetUsersByUsernames requestBody: content: application/json: schema: type: array items: type: string description: List of usernames required: true responses: "200": description: User list retrieval successful content: application/json: schema: type: array items: $ref: '#/components/schemas/User' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' /api/v4/users/search: post: tags: - users summary: Search users description: > Get a list of users based on search criteria provided in the request body. Searches are typically done against username, full name, nickname and email unless otherwise configured by the server. ##### Permissions Requires an active session and `read_channel` and/or `view_team` permissions for any channels or teams specified in the request body. operationId: SearchUsers requestBody: content: application/json: schema: type: object required: - term properties: term: description: The term to match against username, full name, nickname and email type: string team_id: description: If provided, only search users on this team type: string not_in_team_id: description: If provided, only search users not on this team type: string in_channel_id: description: If provided, only search users in this channel type: string not_in_channel_id: description: If provided, only search users not in this channel. Must specifiy `team_id` when using this option type: string in_group_id: description: If provided, only search users in this group. Must have `manage_system` permission. type: string group_constrained: description: When used with `not_in_channel_id` or `not_in_team_id`, returns only the users that are allowed to join the channel or team based on its group constrains. type: boolean allow_inactive: description: When `true`, include deactivated users in the results type: boolean without_team: type: boolean description: Set this to `true` if you would like to search for users that are not on a team. This option takes precendence over `team_id`, `in_channel_id`, and `not_in_channel_id`. limit: description: > The maximum number of users to return in the results __Available as of server version 5.6. Defaults to `100` if not provided or on an earlier server version.__ type: integer default: 100 description: Search criteria required: true responses: "200": description: User list retrieval successful content: application/json: schema: type: array items: $ref: '#/components/schemas/User' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' /api/v4/users/autocomplete: get: tags: - users summary: Autocomplete users description: > Get a list of users for the purpose of autocompleting based on the provided search term. Specify a combination of `team_id` and `channel_id` to filter results further. ##### Permissions Requires an active session and `view_team` and `read_channel` on any teams or channels used to filter the results further. operationId: AutocompleteUsers parameters: - name: team_id in: query description: Team ID schema: type: string - name: channel_id in: query description: Channel ID schema: type: string - name: name in: query description: Username, nickname first name or last name required: true schema: type: string - name: limit in: query description: > The maximum number of users to return in each subresult __Available as of server version 5.6. Defaults to `100` if not provided or on an earlier server version.__ schema: type: integer default: 100 responses: "200": description: User autocomplete successful content: application/json: schema: $ref: '#/components/schemas/UserAutocomplete' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' /api/v4/users/known: get: tags: - users summary: Get user IDs of known users description: | Get the list of user IDs of users with any direct relationship with a user. That means any user sharing any channel, including direct and group channels. ##### Permissions Must be authenticated. __Minimum server version__: 5.23 operationId: GetKnownUsers responses: "200": description: Known users' IDs retrieval successful content: application/json: schema: $ref: '#/components/schemas/KnownUsers' "401": $ref: '#/components/responses/Unauthorized' /api/v4/users/stats: get: tags: - users summary: Get total count of users in the system description: | Get a total count of users in the system. ##### Permissions Must be authenticated. operationId: GetTotalUsersStats responses: "200": description: User stats retrieval successful content: application/json: schema: $ref: '#/components/schemas/UsersStats' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' /api/v4/users/stats/filtered: get: tags: - users summary: Get total count of users in the system matching the specified filters description: | Get a count of users in the system matching the specified filters. __Minimum server version__: 5.26 ##### Permissions Must have `manage_system` permission. operationId: GetTotalUsersStatsFiltered parameters: - name: in_team in: query description: The ID of the team to get user stats for. schema: type: string - name: in_channel in: query description: The ID of the channel to get user stats for. schema: type: string - name: include_deleted in: query description: If deleted accounts should be included in the count. schema: type: boolean - name: include_bots in: query description: If bot accounts should be included in the count. schema: type: boolean - name: roles in: query description: > Comma separated string used to filter users based on any of the specified system roles Example: `?roles=system_admin,system_user` will include users that are either system admins or system users schema: type: string - name: channel_roles in: query description: > Comma separated string used to filter users based on any of the specified channel roles, can only be used in conjunction with `in_channel` Example: `?in_channel=4eb6axxw7fg3je5iyasnfudc5y&channel_roles=channel_user` will include users that are only channel users and not admins or guests schema: type: string - name: team_roles in: query description: > Comma separated string used to filter users based on any of the specified team roles, can only be used in conjunction with `in_team` Example: `?in_team=4eb6axxw7fg3je5iyasnfudc5y&team_roles=team_user` will include users that are only team users and not admins or guests schema: type: string responses: "200": description: Filtered User stats retrieval successful content: application/json: schema: $ref: '#/components/schemas/UsersStats' "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}: get: tags: - users summary: Get a user description: | Get a user a object. Sensitive information will be sanitized out. ##### Permissions Requires an active session but no other permissions. operationId: GetUser parameters: - name: user_id in: path description: User GUID. This can also be "me" which will point to the current user. required: true schema: type: string responses: "200": description: User retrieval successful content: application/json: schema: $ref: '#/components/schemas/User' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "404": $ref: '#/components/responses/NotFound' put: tags: - users summary: Update a user description: > Update a user by providing the user object. The fields that can be updated are defined in the request body, all other provided fields will be ignored. Any fields not included in the request body will be set to null or reverted to default values. ##### Permissions Must be logged in as the user being updated or have the `edit_other_users` permission. operationId: UpdateUser parameters: - name: user_id in: path description: User GUID required: true schema: type: string requestBody: content: application/json: schema: type: object required: - id - email - username properties: id: type: string email: type: string username: type: string first_name: type: string last_name: type: string nickname: type: string locale: type: string position: type: string timezone: $ref: '#/components/schemas/Timezone' props: type: object notify_props: $ref: '#/components/schemas/UserNotifyProps' description: User object that is to be updated required: true responses: "200": description: User update successful content: application/json: schema: $ref: '#/components/schemas/User' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' delete: tags: - users summary: Deactivate a user account. description: > Deactivates the user and revokes all its sessions by archiving its user object. As of server version 5.28, optionally use the `permanent=true` query parameter to permanently delete the user for compliance reasons. To use this feature `ServiceSettings.EnableAPIUserDeletion` must be set to `true` in the server's configuration. ##### Permissions Must be logged in as the user being deactivated or have the `edit_other_users` permission. operationId: DeleteUser parameters: - name: user_id in: path description: User GUID required: true schema: type: string responses: "200": description: User deactivation 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/users/{user_id}/patch: put: tags: - users summary: Patch a user description: > Partially update a user by providing only the fields you want to update. Omitted fields will not be updated. The fields that can be updated are defined in the request body, all other provided fields will be ignored. ##### Permissions Must be logged in as the user being updated or have the `edit_other_users` permission. operationId: PatchUser parameters: - name: user_id in: path description: User GUID required: true schema: type: string requestBody: content: application/json: schema: type: object properties: email: type: string username: type: string first_name: type: string last_name: type: string nickname: type: string locale: type: string position: type: string props: type: object notify_props: $ref: '#/components/schemas/UserNotifyProps' description: User object that is to be updated required: true responses: "200": description: User patch successful content: application/json: schema: $ref: '#/components/schemas/User' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' /api/v4/users/{user_id}/roles: put: tags: - users summary: Update a user's roles description: > Update a user's system-level roles. Valid user roles are "system_user", "system_admin" or both of them. Overwrites any previously assigned system-level roles. ##### Permissions Must have the `manage_roles` permission. operationId: UpdateUserRoles parameters: - 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 system roles to assign to the user required: true responses: "200": description: User 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/users/{user_id}/active: put: tags: - users summary: Update user active status description: > Update user active or inactive status. __Since server version 4.6, users using a SSO provider to login can be activated or deactivated with this endpoint. However, if their activation status in Mattermost does not reflect their status in the SSO provider, the next synchronization or login by that user will reset the activation status to that of their account in the SSO provider. Server versions 4.5 and before do not allow activation or deactivation of SSO users from this endpoint.__ ##### Permissions User can deactivate themselves. User with `manage_system` permission can activate or deactivate a user. operationId: UpdateUserActive parameters: - name: user_id in: path description: User GUID required: true schema: type: string requestBody: content: application/json: schema: type: object required: - active properties: active: type: boolean description: Use `true` to set the user active, `false` for inactive required: true responses: "200": description: User active status 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/users/{user_id}/image: get: tags: - users summary: Get user's profile image description: | Get a user's profile image based on user_id string parameter. ##### Permissions Must be logged in. operationId: GetProfileImage parameters: - name: user_id in: path description: User GUID required: true schema: type: string - name: _ in: query description: Not used by the server. Clients can pass in the last picture update time of the user to potentially take advantage of caching schema: type: number responses: "200": description: User's profile image "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "501": $ref: '#/components/responses/NotImplemented' post: tags: - users summary: Set user's profile image description: > Set a user's profile image based on user_id string parameter. ##### Permissions Must be logged in as the user being updated or have the `edit_other_users` permission. operationId: SetProfileImage parameters: - name: user_id in: path description: User GUID required: true schema: type: string requestBody: content: multipart/form-data: schema: type: object properties: image: description: The image to be uploaded type: string format: binary required: - image responses: "200": description: Profile image set 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' "501": $ref: '#/components/responses/NotImplemented' delete: tags: - users summary: Delete user's profile image description: > Delete user's profile image and reset to default image based on user_id string parameter. ##### Permissions Must be logged in as the user being updated or have the `edit_other_users` permission. __Minimum server version__: 5.5 operationId: SetDefaultProfileImage parameters: - name: user_id in: path description: User GUID required: true schema: type: string responses: "200": description: Profile image reset 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' "501": $ref: '#/components/responses/NotImplemented' /api/v4/users/{user_id}/image/default: get: tags: - users summary: Return user's default (generated) profile image description: > Returns the default (generated) user profile image based on user_id string parameter. ##### Permissions Must be logged in. __Minimum server version__: 5.5 operationId: GetDefaultProfileImage parameters: - name: user_id in: path description: User GUID required: true schema: type: string responses: "200": description: Default profile image "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "501": $ref: '#/components/responses/NotImplemented' /api/v4/users/username/{username}: get: tags: - users summary: Get a user by username description: > Get a user object by providing a username. Sensitive information will be sanitized out. ##### Permissions Requires an active session but no other permissions. operationId: GetUserByUsername parameters: - name: username in: path description: Username required: true schema: type: string responses: "200": description: User retrieval successful content: application/json: schema: $ref: '#/components/schemas/User' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "404": $ref: '#/components/responses/NotFound' /api/v4/users/password/reset: post: tags: - users summary: Reset password description: > Update the password for a user using a one-use, timed recovery code tied to the user's account. Only works for non-SSO users. ##### Permissions No permissions required. operationId: ResetPassword requestBody: content: application/json: schema: type: object required: - code - new_password properties: code: description: The recovery code type: string new_password: description: The new password for the user type: string required: true responses: "200": description: User password 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/users/{user_id}/mfa: put: tags: - users summary: Update a user's MFA description: > Activates multi-factor authentication for the user if `activate` is true and a valid `code` is provided. If activate is false, then `code` is not required and multi-factor authentication is disabled for the user. ##### Permissions Must be logged in as the user being updated or have the `edit_other_users` permission. operationId: UpdateUserMfa parameters: - name: user_id in: path description: User GUID required: true schema: type: string requestBody: content: application/json: schema: type: object required: - activate properties: activate: description: Use `true` to activate, `false` to deactivate type: boolean code: description: The code produced by your MFA client. Required if `activate` is true type: string required: true responses: "200": description: User MFA 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' "501": $ref: '#/components/responses/NotImplemented' /api/v4/users/{user_id}/mfa/generate: post: tags: - users summary: Generate MFA secret description: > Generates an multi-factor authentication secret for a user and returns it as a string and as base64 encoded QR code image. ##### Permissions Must be logged in as the user or have the `edit_other_users` permission. operationId: GenerateMfaSecret parameters: - name: user_id in: path description: User GUID required: true schema: type: string responses: "200": description: MFA secret generation successful content: application/json: schema: type: object properties: secret: description: The MFA secret as a string type: string qr_code: description: A base64 encoded QR code image type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "501": $ref: '#/components/responses/NotImplemented' /api/v4/users/{user_id}/demote: post: tags: - users summary: Demote a user to a guest description: | Convert a regular user into a guest. This will convert the user into a guest for the whole system while retaining their existing team and channel memberships. __Minimum server version__: 5.16 ##### Permissions Must be logged in as the user or have the `demote_to_guest` permission. operationId: DemoteUserToGuest parameters: - name: user_id in: path description: User GUID required: true schema: type: string responses: "200": description: User successfully demoted 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' "501": $ref: '#/components/responses/NotImplemented' /api/v4/users/{user_id}/promote: post: tags: - users summary: Promote a guest to user description: | Convert a guest into a regular user. This will convert the guest into a user for the whole system while retaining any team and channel memberships and automatically joining them to the default channels. __Minimum server version__: 5.16 ##### Permissions Must be logged in as the user or have the `promote_guest` permission. operationId: PromoteGuestToUser parameters: - name: user_id in: path description: User GUID required: true schema: type: string responses: "200": description: Guest successfully promoted 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' "501": $ref: '#/components/responses/NotImplemented' /api/v4/users/{user_id}/convert_to_bot: post: tags: - bots - users summary: Convert a user into a bot description: | Convert a user into a bot. __Minimum server version__: 5.26 ##### Permissions Must have `manage_system` permission. operationId: ConvertUserToBot parameters: - name: user_id in: path description: User GUID required: true schema: type: string responses: "200": description: User successfully converted 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/users/mfa: post: tags: - users summary: Check MFA description: > Check if a user has multi-factor authentication active on their account by providing a login id. Used to check whether an MFA code needs to be provided when logging in. ##### Permissions No permission required. operationId: CheckUserMfa requestBody: content: application/json: schema: type: object required: - login_id properties: login_id: description: The email or username used to login type: string required: true responses: "200": description: MFA check successful content: application/json: schema: type: object properties: mfa_required: description: Value will `true` if MFA is active, `false` otherwise type: boolean "400": $ref: '#/components/responses/BadRequest' /api/v4/users/{user_id}/password: put: tags: - users summary: Update a user's password description: > Update a user's password. New password must meet password policy set by server configuration. Current password is required if you're updating your own password. ##### Permissions Must be logged in as the user the password is being changed for or have `manage_system` permission. operationId: UpdateUserPassword parameters: - name: user_id in: path description: User GUID required: true schema: type: string requestBody: content: application/json: schema: type: object required: - new_password properties: current_password: description: The current password for the user type: string new_password: description: The new password for the user type: string required: true responses: "200": description: User password 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/users/password/reset/send: post: tags: - users summary: Send password reset email description: > Send an email containing a link for resetting the user's password. The link will contain a one-use, timed recovery code tied to the user's account. Only works for non-SSO users. ##### Permissions No permissions required. operationId: SendPasswordResetEmail requestBody: content: application/json: schema: type: object required: - email properties: email: description: The email of the user type: string required: true responses: "200": description: Email sent if account exists 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/users/email/{email}: get: tags: - users summary: Get a user by email description: > Get a user object by providing a user email. Sensitive information will be sanitized out. ##### Permissions Requires an active session and for the current session to be able to view another user's email based on the server's privacy settings. operationId: GetUserByEmail parameters: - name: email in: path description: User Email required: true schema: type: string responses: "200": description: User retrieval successful content: application/json: schema: $ref: '#/components/schemas/User' "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}/sessions: get: tags: - users summary: Get user's sessions description: > Get a list of sessions by providing the user GUID. Sensitive information will be sanitized out. ##### Permissions Must be logged in as the user being updated or have the `edit_other_users` permission. operationId: GetSessions parameters: - name: user_id in: path description: User GUID required: true schema: type: string responses: "200": description: User session retrieval successful content: application/json: schema: type: array items: $ref: '#/components/schemas/Session' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' /api/v4/users/{user_id}/sessions/revoke: post: tags: - users summary: Revoke a user session description: > Revokes a user session from the provided user id and session id strings. ##### Permissions Must be logged in as the user being updated or have the `edit_other_users` permission. operationId: RevokeSession parameters: - name: user_id in: path description: User GUID required: true schema: type: string requestBody: content: application/json: schema: type: object required: - session_id properties: session_id: description: The session GUID to revoke. type: string required: true responses: "200": description: User session revoked 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/users/{user_id}/sessions/revoke/all: post: tags: - users summary: Revoke all active sessions for a user description: > Revokes all user sessions from the provided user id and session id strings. ##### Permissions Must be logged in as the user being updated or have the `edit_other_users` permission. __Minimum server version__: 4.4 operationId: RevokeAllSessions parameters: - name: user_id in: path description: User GUID required: true schema: type: string responses: "200": description: User sessions revoked successfully 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/users/sessions/device: put: tags: - users summary: Attach mobile device description: > Attach a mobile device id to the currently logged in session. This will enable push notifications for a user, if configured by the server. ##### Permissions Must be authenticated. operationId: AttachDeviceId requestBody: content: application/json: schema: type: object required: - device_id properties: device_id: description: Mobile device id. For Android prefix the id with `android:` and Apple with `apple:` type: string required: true responses: "200": description: Device id attach successful content: application/json: schema: $ref: '#/components/schemas/StatusOK' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' /api/v4/users/{user_id}/audits: get: tags: - users summary: Get user's audits description: | Get a list of audit by providing the user GUID. ##### Permissions Must be logged in as the user or have the `edit_other_users` permission. operationId: GetUserAudits parameters: - name: user_id in: path description: User GUID required: true schema: type: string responses: "200": description: User audits retrieval successful content: application/json: schema: type: array items: $ref: '#/components/schemas/Audit' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' /api/v4/users/{user_id}/email/verify/member: post: tags: - users summary: Verify user email by ID description: | Verify the email used by a user without a token. __Minimum server version__: 5.24 ##### Permissions Must have `manage_system` permission. operationId: VerifyUserEmailWithoutToken parameters: - name: user_id in: path description: User GUID required: true schema: type: string responses: "200": description: User email verification successful content: application/json: schema: $ref: '#/components/schemas/User' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "404": $ref: '#/components/responses/NotFound' /api/v4/users/email/verify: post: tags: - users summary: Verify user email description: | Verify the email used by a user to sign-up their account with. ##### Permissions No permissions required. operationId: VerifyUserEmail requestBody: content: application/json: schema: type: object required: - token properties: token: description: The token given to validate the email type: string required: true responses: "200": description: User email verification successful content: application/json: schema: $ref: '#/components/schemas/StatusOK' "400": $ref: '#/components/responses/BadRequest' /api/v4/users/email/verify/send: post: tags: - users summary: Send verification email description: > Send an email with a verification link to a user that has an email matching the one in the request body. This endpoint will return success even if the email does not match any users on the system. ##### Permissions No permissions required. operationId: SendVerificationEmail requestBody: content: application/json: schema: type: object required: - email properties: email: description: Email of a user type: string required: true responses: "200": description: Email send successful if email exists content: application/json: schema: $ref: '#/components/schemas/StatusOK' "400": $ref: '#/components/responses/BadRequest' /api/v4/users/login/switch: post: tags: - users summary: Switch login method description: > Switch a user's login method from using email to OAuth2/SAML/LDAP or back to email. When switching to OAuth2/SAML, account switching is not complete until the user follows the returned link and completes any steps on the OAuth2/SAML service provider. To switch from email to OAuth2/SAML, specify `current_service`, `new_service`, `email` and `password`. To switch from OAuth2/SAML to email, specify `current_service`, `new_service`, `email` and `new_password`. To switch from email to LDAP/AD, specify `current_service`, `new_service`, `email`, `password`, `ldap_ip` and `new_password` (this is the user's LDAP password). To switch from LDAP/AD to email, specify `current_service`, `new_service`, `ldap_ip`, `password` (this is the user's LDAP password), `email` and `new_password`. Additionally, specify `mfa_code` when trying to switch an account on LDAP/AD or email that has MFA activated. ##### Permissions No current authentication required except when switching from OAuth2/SAML to email. operationId: SwitchAccountType requestBody: content: application/json: schema: type: object required: - current_service - new_service properties: current_service: description: The service the user currently uses to login type: string new_service: description: The service the user will use to login type: string email: description: The email of the user type: string password: description: The password used with the current service type: string mfa_code: description: The MFA code of the current service type: string ldap_id: description: The LDAP/AD id of the user type: string required: true responses: "200": description: Login method switch or request successful content: application/json: schema: type: object properties: follow_link: description: The link for the user to follow to login or to complete the account switching when the current service is OAuth2/SAML type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "501": $ref: '#/components/responses/NotImplemented' /api/v4/users/{user_id}/tokens: post: tags: - users summary: Create a user access token description: > Generate a user access token that can be used to authenticate with the Mattermost REST API. __Minimum server version__: 4.1 ##### Permissions Must have `create_user_access_token` permission. For non-self requests, must also have the `edit_other_users` permission. operationId: CreateUserAccessToken parameters: - name: user_id in: path description: User GUID required: true schema: type: string requestBody: content: application/json: schema: type: object required: - description properties: description: description: A description of the token usage type: string required: true responses: "201": description: User access token creation successful content: application/json: schema: $ref: '#/components/schemas/UserAccessToken' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' get: tags: - users summary: Get user access tokens description: > Get a list of user access tokens for a user. Does not include the actual authentication tokens. Use query parameters for paging. __Minimum server version__: 4.1 ##### Permissions Must have `read_user_access_token` permission. For non-self requests, must also have the `edit_other_users` permission. operationId: GetUserAccessTokensForUser parameters: - name: user_id in: path description: User 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 tokens per page. schema: type: integer default: 60 responses: "200": description: User access tokens retrieval successful content: application/json: schema: type: array items: $ref: '#/components/schemas/UserAccessTokenSanitized' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' /api/v4/users/tokens: get: tags: - users summary: Get user access tokens description: > Get a page of user access tokens for users on the system. Does not include the actual authentication tokens. Use query parameters for paging. __Minimum server version__: 4.7 ##### Permissions Must have `manage_system` permission. operationId: GetUserAccessTokens parameters: - name: page in: query description: The page to select. schema: type: integer default: 0 - name: per_page in: query description: The number of tokens per page. schema: type: integer default: 60 responses: "200": description: User access tokens retrieval successful content: application/json: schema: type: array items: $ref: '#/components/schemas/UserAccessTokenSanitized' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' /api/v4/users/tokens/revoke: post: tags: - users summary: Revoke a user access token description: > Revoke a user access token and delete any sessions using the token. __Minimum server version__: 4.1 ##### Permissions Must have `revoke_user_access_token` permission. For non-self requests, must also have the `edit_other_users` permission. operationId: RevokeUserAccessToken requestBody: content: application/json: schema: type: object required: - token_id properties: token_id: description: The user access token GUID to revoke type: string required: true responses: "200": description: User access token revoke 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/users/tokens/{token_id}: get: tags: - users summary: Get a user access token description: > Get a user access token. Does not include the actual authentication token. __Minimum server version__: 4.1 ##### Permissions Must have `read_user_access_token` permission. For non-self requests, must also have the `edit_other_users` permission. operationId: GetUserAccessToken parameters: - name: token_id in: path description: User access token GUID required: true schema: type: string responses: "200": description: User access token retrieval successful content: application/json: schema: $ref: '#/components/schemas/UserAccessTokenSanitized' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' /api/v4/users/tokens/disable: post: tags: - users summary: Disable personal access token description: > Disable a personal access token and delete any sessions using the token. The token can be re-enabled using `/users/tokens/enable`. __Minimum server version__: 4.4 ##### Permissions Must have `revoke_user_access_token` permission. For non-self requests, must also have the `edit_other_users` permission. operationId: DisableUserAccessToken requestBody: content: application/json: schema: type: object required: - token_id properties: token_id: description: The personal access token GUID to disable type: string required: true responses: "200": description: Personal access token disable 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/users/tokens/enable: post: tags: - users summary: Enable personal access token description: > Re-enable a personal access token that has been disabled. __Minimum server version__: 4.4 ##### Permissions Must have `create_user_access_token` permission. For non-self requests, must also have the `edit_other_users` permission. operationId: EnableUserAccessToken requestBody: content: application/json: schema: type: object required: - token_id properties: token_id: description: The personal access token GUID to enable type: string required: true responses: "200": description: Personal access token enable 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/users/tokens/search: post: tags: - users summary: Search tokens description: > Get a list of tokens based on search criteria provided in the request body. Searches are done against the token id, user id and username. __Minimum server version__: 4.7 ##### Permissions Must have `manage_system` permission. operationId: SearchUserAccessTokens requestBody: content: application/json: schema: type: object required: - term properties: term: description: The search term to match against the token id, user id or username. type: string description: Search criteria required: true responses: "200": description: Personal access token search successful content: application/json: schema: type: array items: $ref: '#/components/schemas/UserAccessTokenSanitized' /api/v4/users/{user_id}/auth: put: tags: - users summary: Update a user's authentication method description: > Updates a user's authentication method. This can be used to change them to/from LDAP authentication for example. __Minimum server version__: 4.6 ##### Permissions Must have the `edit_other_users` permission. operationId: UpdateUserAuth parameters: - name: user_id in: path description: User GUID required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/UserAuthData' required: true responses: "200": description: User auth update successful content: application/json: schema: $ref: '#/components/schemas/UserAuthData' "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}/terms_of_service: post: tags: - users - terms of service summary: Records user action when they accept or decline custom terms of service description: > Records user action when they accept or decline custom terms of service. Records the action in audit table. Updates user's last accepted terms of service ID if they accepted it. __Minimum server version__: 5.4 ##### Permissions Must be logged in as the user being acted on. operationId: RegisterTermsOfServiceAction parameters: - name: user_id in: path description: User GUID required: true schema: type: string requestBody: content: application/json: schema: type: object required: - serviceTermsId - accepted properties: serviceTermsId: description: terms of service ID on which the user is acting on type: string accepted: description: true or false, indicates whether the user accepted or rejected the terms of service. type: string description: terms of service details required: true responses: "200": description: Terms of service action recorded successfully content: application/json: schema: $ref: '#/components/schemas/StatusOK' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' get: tags: - users - terms of service summary: Fetches user's latest terms of service action if the latest action was for acceptance. description: > Will be deprecated in v6.0 Fetches user's latest terms of service action if the latest action was for acceptance. __Minimum server version__: 5.6 ##### Permissions Must be logged in as the user being acted on. operationId: GetUserTermsOfService parameters: - name: user_id in: path description: User GUID required: true schema: type: string responses: "200": description: User's accepted terms of service action content: application/json: schema: $ref: '#/components/schemas/UserTermsOfService' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "404": description: User hasn't performed an action or the latest action was a rejection. content: application/json: schema: $ref: '#/components/schemas/AppError' /api/v4/users/sessions/revoke/all: post: tags: - users summary: Revoke all sessions from all users. description: > For any session currently on the server (including admin) it will be revoked. Clients will be notified to log out users. __Minimum server version__: 5.14 ##### Permissions Must have `manage_system` permission. operationId: RevokeSessionsFromAllUsers responses: "200": description: Sessions successfully revoked. "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' /api/v4/users/{user_id}/typing: post: tags: - users summary: Publish a user typing websocket event. description: > Notify users in the given channel via websocket that the given user is typing. __Minimum server version__: 5.26 ##### Permissions Must have `manage_system` permission to publish for any user other than oneself. operationId: PublishUserTyping parameters: - name: user_id in: path description: User GUID required: true schema: type: string requestBody: content: application/json: schema: type: object required: - channel_id properties: channel_id: description: The id of the channel to which to direct the typing event. type: string parent_id: description: The optional id of the root post of the thread to which the user is replying. If unset, the typing event is directed at the entire channel. type: string responses: "200": description: User typing websocket event accepted for publishing. "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' /api/v4/users/{user_id}/uploads: get: tags: - users summary: Get uploads for a user description: | Gets all the upload sessions belonging to a user. __Minimum server version__: 5.28 ##### Permissions Must be logged in as the user who created the upload sessions. operationId: GetUploadsForUser 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 responses: "200": description: User's uploads retrieval successful content: application/json: schema: type: array items: $ref: '#/components/schemas/UploadSession' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "404": $ref: '#/components/responses/NotFound' /api/v4/users/{user_id}/channel_members: get: tags: - users summary: Get all channel members from all teams for a user description: | Get all channel members from all teams for a user. __Minimum server version__: 6.2.0 ##### Permissions Logged in as the user, or have `edit_other_users` permission. operationId: GetChannelMembersWithTeamDataForUser 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: page in: query description: Page specifies which part of the results to return, by PageSize. schema: type: integer - name: pageSize in: query description: PageSize specifies the size of the returned chunk of results. schema: type: integer responses: "200": description: User's uploads retrieval successful content: application/json: schema: type: array items: $ref: '#/components/schemas/ChannelMemberWithTeamData' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "404": $ref: '#/components/responses/NotFound' /api/v4/users/migrate_auth/ldap: post: tags: - users - migrate - authentication - LDAP summary: Migrate user accounts authentication type to LDAP. description: > Migrates accounts from one authentication provider to another. For example, you can upgrade your authentication provider from email to LDAP. __Minimum server version__: 5.28 ##### Permissions Must have `manage_system` permission. operationId: MigrateAuthToLdap requestBody: content: application/json: schema: type: object required: - from - match_field - force properties: from: description: The current authentication type for the matched users. type: string match_field: description: Foreign user field name to match. type: string force: type: boolean responses: "200": description: Successfully migrated authentication type to LDAP. "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "501": $ref: '#/components/responses/NotImplemented' /api/v4/users/migrate_auth/saml: post: tags: - users - migrate - authentication - SAML summary: Migrate user accounts authentication type to SAML. description: > Migrates accounts from one authentication provider to another. For example, you can upgrade your authentication provider from email to SAML. __Minimum server version__: 5.28 ##### Permissions Must have `manage_system` permission. operationId: MigrateAuthToSaml requestBody: content: application/json: schema: type: object required: - from - matches - auto properties: from: description: The current authentication type for the matched users. type: string matches: description: Users map. type: object auto: type: boolean responses: "200": description: Successfully migrated authentication type to LDAP. "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}/threads: get: tags: - threads summary: Get all threads that user is following description: | Get all threads that user is following __Minimum server version__: 5.29 ##### Permissions Must be logged in as the user or have `edit_other_users` permission. operationId: GetUserThreads 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: team_id in: path description: The ID of the team in which the thread is. required: true schema: type: string - name: since in: query description: Since filters the threads based on their LastUpdateAt timestamp. schema: type: integer - name: deleted in: query description: Deleted will specify that even deleted threads should be returned (For mobile sync). schema: type: boolean default: false - name: extended in: query description: Extended will enrich the response with participant details. schema: type: boolean default: false - name: page in: query description: Page specifies which part of the results to return, by PageSize. schema: type: integer default: 0 - name: pageSize in: query description: PageSize specifies the size of the returned chunk of results. schema: default: 30 type: integer - name: totalsOnly in: query description: Setting this to true will only return the total counts. schema: type: boolean default: false - name: threadsOnly in: query description: Setting this to true will only return threads. schema: type: boolean default: false responses: "200": description: User's thread retrieval successful content: application/json: schema: $ref: '#/components/schemas/UserThreads' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "404": $ref: '#/components/responses/NotFound' /api/v4/users/{user_id}/teams/{team_id}/threads/mention_counts: get: tags: - threads summary: Get all unread mention counts from followed threads, per-channel description: | Get all unread mention counts from followed threads __Minimum server version__: 5.29 ##### Permissions Must be logged in as the user or have `edit_other_users` permission. operationId: GetThreadMentionCountsByChannel 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: team_id in: path description: The ID of the team in which the thread is. required: true schema: type: string responses: "200": description: Get was successful "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "404": $ref: '#/components/responses/NotFound' /api/v4/users/{user_id}/teams/{team_id}/threads/read: put: tags: - threads summary: Mark all threads that user is following as read description: | Mark all threads that user is following as read __Minimum server version__: 5.29 ##### Permissions Must be logged in as the user or have `edit_other_users` permission. operationId: UpdateThreadsReadForUser 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: team_id in: path description: The ID of the team in which the thread is. required: true schema: type: string responses: "200": description: User's thread update successful "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "404": $ref: '#/components/responses/NotFound' /api/v4/users/{user_id}/teams/{team_id}/threads/{thread_id}/read/{timestamp}: put: tags: - threads summary: Mark a thread that user is following read state to the timestamp description: | Mark a thread that user is following as read __Minimum server version__: 5.29 ##### Permissions Must be logged in as the user or have `edit_other_users` permission. operationId: UpdateThreadReadForUser 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: team_id in: path description: The ID of the team in which the thread is. required: true schema: type: string - name: thread_id in: path description: The ID of the thread to update required: true schema: type: string - name: timestamp in: path description: The timestamp to which the thread's "last read" state will be reset. required: true schema: type: string responses: "200": description: User's thread update successful "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "404": $ref: '#/components/responses/NotFound' /api/v4/users/{user_id}/teams/{team_id}/threads/{thread_id}/set_unread/{post_id}: post: tags: - threads summary: Mark a thread that user is following as unread based on a post id description: | Mark a thread that user is following as unread __Minimum server version__: 6.7 ##### Permissions Must have `read_channel` permission for the channel the thread is in or if the channel is public, have the `read_public_channels` permission for the team. Must have `edit_other_users` permission if the user is not the one marking the thread for himself. operationId: SetThreadUnreadByPostId 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: team_id in: path description: The ID of the team in which the thread is. required: true schema: type: string - name: thread_id in: path description: The ID of the thread to update required: true schema: type: string - name: post_id in: path description: The ID of a post belonging to the thread to mark as unread. required: true schema: type: string responses: "200": description: User's thread update successful "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "404": $ref: '#/components/responses/NotFound' /api/v4/users/{user_id}/teams/{team_id}/threads/{thread_id}/following: put: tags: - threads summary: Start following a thread description: | Start following a thread __Minimum server version__: 5.29 ##### Permissions Must be logged in as the user or have `edit_other_users` permission. operationId: StartFollowingThread 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: team_id in: path description: The ID of the team in which the thread is. required: true schema: type: string - name: thread_id in: path description: The ID of the thread to follow required: true schema: type: string responses: "200": description: User's thread update successful "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "404": $ref: '#/components/responses/NotFound' delete: tags: - threads summary: Stop following a thread description: | Stop following a thread __Minimum server version__: 5.29 ##### Permissions Must be logged in as the user or have `edit_other_users` permission. operationId: StopFollowingThread 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: team_id in: path description: The ID of the team in which the thread is. required: true schema: type: string - name: thread_id in: path description: The ID of the thread to update required: true schema: type: string responses: "200": description: User's thread update successful "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "404": $ref: '#/components/responses/NotFound' /api/v4/users/{user_id}/teams/{team_id}/threads/{thread_id}: get: tags: - threads summary: Get a thread followed by the user description: | Get a thread __Minimum server version__: 5.29 ##### Permissions Must be logged in as the user or have `edit_other_users` permission. operationId: GetUserThread 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: team_id in: path description: The ID of the team in which the thread is. required: true schema: type: string - name: thread_id in: path description: The ID of the thread to follow required: true schema: type: string responses: "200": description: Get was successful "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "404": $ref: '#/components/responses/NotFound' /api/v4/users/{user_id}/data_retention/team_policies: get: tags: - data retention summary: Get the policies which are applied to a user's teams description: | Gets the policies which are applied to the all of the teams to which a user belongs. __Minimum server version__: 5.35 ##### Permissions Must be logged in as the user or have the `manage_system` permission. ##### License Requires an E20 license. operationId: GetTeamPoliciesForUser 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: page in: query description: The page to select. schema: type: integer default: 0 - name: per_page in: query description: The number of policies per page. There is a maximum limit of 200 per page. schema: type: integer default: 60 responses: "200": description: Teams for retention policy successfully retrieved. content: application/json: schema: $ref: '#/components/schemas/RetentionPolicyForTeamList' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "500": $ref: '#/components/responses/InternalServerError' "501": $ref: '#/components/responses/NotImplemented' /api/v4/users/{user_id}/data_retention/channel_policies: get: tags: - data retention summary: Get the policies which are applied to a user's channels description: | Gets the policies which are applied to the all of the channels to which a user belongs. __Minimum server version__: 5.35 ##### Permissions Must be logged in as the user or have the `manage_system` permission. ##### License Requires an E20 license. operationId: GetChannelPoliciesForUser 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: page in: query description: The page to select. schema: type: integer default: 0 - name: per_page in: query description: The number of policies per page. There is a maximum limit of 200 per page. schema: type: integer default: 60 responses: "200": description: Channels for retention policy successfully retrieved. content: application/json: schema: $ref: '#/components/schemas/RetentionPolicyForChannelList' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "500": $ref: '#/components/responses/InternalServerError' "501": $ref: '#/components/responses/NotImplemented' /api/v4/users/invalid_emails: get: tags: - users summary: Get users with invalid emails description: > Get users whose emails are considered invalid. It is an error to invoke this API if your team settings enable an open server. ##### Permissions Requires `sysconsole_read_user_management_users`. operationId: GetUsersWithInvalidEmails parameters: - 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. There is a maximum limit of 200 users per page. schema: type: integer default: 60 responses: "200": description: User page retrieval successful content: application/json: schema: type: array items: $ref: '#/components/schemas/User' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' /api/v4/users/{user_id}/status: get: tags: - status summary: Get user status description: | Get user status by id from the server. ##### Permissions Must be authenticated. operationId: GetUserStatus parameters: - name: user_id in: path description: User ID required: true schema: type: string responses: "200": description: User status retrieval successful content: application/json: schema: $ref: '#/components/schemas/Status' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' put: tags: - status summary: Update user status description: > Manually set a user's status. When setting a user's status, the status will remain that value until set "online" again, which will return the status to being automatically updated based on user activity. ##### Permissions Must have `edit_other_users` permission for the team. operationId: UpdateUserStatus parameters: - name: user_id in: path description: User ID required: true schema: type: string requestBody: content: application/json: schema: type: object required: - status - user_id properties: user_id: type: string description: User ID status: type: string description: User status, can be `online`, `away`, `offline` and `dnd` dnd_end_time: type: integer description: Time in epoch seconds at which a dnd status would be unset. description: Status object that is to be updated required: true responses: "200": description: User status update successful content: application/json: schema: $ref: '#/components/schemas/Status' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' /api/v4/users/status/ids: post: tags: - status summary: Get user statuses by id description: | Get a list of user statuses by id from the server. ##### Permissions Must be authenticated. operationId: GetUsersStatusesByIds requestBody: content: application/json: schema: type: array items: type: string description: List of user ids to fetch required: true responses: "200": description: User statuses retrieval successful content: application/json: schema: type: array items: $ref: '#/components/schemas/Status' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' /api/v4/users/{user_id}/status/custom: put: tags: - status summary: Update user custom status description: | Updates a user's custom status by setting the value in the user's props and updates the user. Also save the given custom status to the recent custom statuses in the user's props ##### Permissions Must be logged in as the user whose custom status is being updated. operationId: UpdateUserCustomStatus parameters: - name: user_id in: path description: User ID required: true schema: type: string requestBody: content: application/json: schema: type: object required: - emoji - text properties: emoji: type: string description: Any emoji text: type: string description: Any custom status text duration: type: string description: Duration of custom status, can be `thirty_minutes`, `one_hour`, `four_hours`, `today`, `this_week` or `date_and_time` expires_at: type: string description: The time at which custom status should be expired. It should be in ISO format. description: Custom status object that is to be updated required: true responses: "200": description: User custom status update successful "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' delete: tags: - status summary: Unsets user custom status description: | Unsets a user's custom status by updating the user's props and updates the user ##### Permissions Must be logged in as the user whose custom status is being removed. operationId: UnsetUserCustomStatus parameters: - name: user_id in: path description: User ID required: true schema: type: string responses: "200": description: User custom status delete successful "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' /api/v4/users/{user_id}/status/custom/recent: delete: tags: - status summary: Delete user's recent custom status description: | Deletes a user's recent custom status by removing the specific status from the recentCustomStatuses in the user's props and updates the user. ##### Permissions Must be logged in as the user whose recent custom status is being deleted. operationId: RemoveRecentCustomStatus parameters: - name: user_id in: path description: User ID required: true schema: type: string requestBody: content: application/json: schema: type: object required: - emoji - text - duration - expires_at properties: emoji: type: string description: Any emoji text: type: string description: Any custom status text duration: type: string description: Duration of custom status, can be `thirty_minutes`, `one_hour`, `four_hours`, `today`, `this_week` or `date_and_time` expires_at: type: string description: The time at which custom status should be expired. It should be in ISO format. description: Custom Status object that is to be removed from the recent custom statuses. required: true responses: "200": description: User recent custom status delete successful "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' /api/v4/users/{user_id}/status/custom/recent/delete: post: tags: - status summary: Delete user's recent custom status description: | Deletes a user's recent custom status by removing the specific status from the recentCustomStatuses in the user's props and updates the user. ##### Permissions Must be logged in as the user whose recent custom status is being deleted. operationId: PostUserRecentCustomStatusDelete parameters: - name: user_id in: path description: User ID required: true schema: type: string requestBody: content: application/json: schema: type: object required: - emoji - text - duration - expires_at properties: emoji: type: string description: Any emoji text: type: string description: Any custom status text duration: type: string description: Duration of custom status, can be `thirty_minutes`, `one_hour`, `four_hours`, `today`, `this_week` or `date_and_time` expires_at: type: string description: The time at which custom status should be expired. It should be in ISO format. description: Custom Status object that is to be removed from the recent custom statuses. required: true responses: "200": description: User recent custom status delete successful "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' /api/v4/teams: post: tags: - teams summary: Create a team description: | Create a new team on the system. ##### Permissions Must be authenticated and have the `create_team` permission. operationId: CreateTeam requestBody: content: application/json: schema: type: object required: - name - display_name - type properties: name: type: string description: Unique handler for a team, will be present in the team URL display_name: type: string description: Non-unique UI name for the team type: type: string description: "`'O'` for open, `'I'` for invite only" description: Team that is to be created required: true responses: "201": description: Team creation successful content: application/json: schema: $ref: '#/components/schemas/Team' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' get: tags: - teams summary: Get teams description: > For regular users only returns open teams. Users with the "manage_system" permission will return teams regardless of type. The result is based on query string parameters - page and per_page. ##### Permissions Must be authenticated. "manage_system" permission is required to show all teams. operationId: GetAllTeams parameters: - name: page in: query description: The page to select. schema: type: integer default: 0 - name: per_page in: query description: The number of teams per page. schema: type: integer default: 60 - name: include_total_count description: "Appends a total count of returned teams inside the response object - ex: `{ \"teams\": [], \"total_count\" : 0 }`. " in: query schema: type: boolean default: false - name: exclude_policy_constrained in: query schema: type: boolean default: false description: >- If set to true, teams 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: Team list retrieval successful content: application/json: schema: type: array items: $ref: '#/components/schemas/Team' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' /api/v4/teams/{team_id}: get: tags: - teams summary: Get a team description: | Get a team on the system. ##### Permissions Must be authenticated and have the `view_team` permission. operationId: GetTeam parameters: - name: team_id in: path description: Team GUID required: true schema: type: string responses: "200": description: Team retrieval successful content: application/json: schema: $ref: '#/components/schemas/Team' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' put: tags: - teams summary: Update a team description: > Update a team by providing the team object. The fields that can be updated are defined in the request body, all other provided fields will be ignored. ##### Permissions Must have the `manage_team` permission. operationId: UpdateTeam parameters: - name: team_id in: path description: Team GUID required: true schema: type: string requestBody: content: application/json: schema: type: object required: - id - display_name - description - company_name - allowed_domains - invite_id - allow_open_invite properties: id: type: string display_name: type: string description: type: string company_name: type: string allowed_domains: type: string invite_id: type: string allow_open_invite: type: string description: Team to update required: true responses: "200": description: Team update successful content: application/json: schema: $ref: '#/components/schemas/Team' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' delete: tags: - teams summary: Delete a team description: > Soft deletes a team, by marking the team as deleted in the database. Soft deleted teams will not be accessible in the user interface. Optionally use the permanent query parameter to hard delete the team for compliance reasons. As of server version 5.0, to use this feature `ServiceSettings.EnableAPITeamDeletion` must be set to `true` in the server's configuration. ##### Permissions Must have the `manage_team` permission. operationId: SoftDeleteTeam parameters: - name: team_id in: path description: Team GUID required: true schema: type: string - name: permanent in: query description: Permanently delete the team, to be used for compliance reasons only. As of server version 5.0, `ServiceSettings.EnableAPITeamDeletion` must be set to `true` in the server's configuration. schema: type: boolean default: false responses: "200": description: Team 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' "404": $ref: '#/components/responses/NotFound' /api/v4/teams/{team_id}/patch: put: tags: - teams summary: Patch a team description: > Partially update a team by providing only the fields you want to update. Omitted fields will not be updated. The fields that can be updated are defined in the request body, all other provided fields will be ignored. ##### Permissions Must have the `manage_team` permission. operationId: PatchTeam parameters: - name: team_id in: path description: Team GUID required: true schema: type: string requestBody: content: application/json: schema: type: object properties: display_name: type: string description: type: string company_name: type: string invite_id: type: string allow_open_invite: type: boolean description: Team object that is to be updated required: true responses: "200": description: team patch successful content: application/json: schema: $ref: '#/components/schemas/Team' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' /api/v4/teams/{team_id}/privacy: put: tags: - teams summary: Update teams's privacy description: > Updates team's privacy allowing changing a team from Public (open) to Private (invitation only) and back. __Minimum server version__: 5.24 ##### Permissions `manage_team` permission for the team of the team. operationId: UpdateTeamPrivacy parameters: - name: team_id in: path description: Team GUID required: true schema: type: string requestBody: content: application/json: schema: type: object required: - privacy properties: privacy: type: string description: "Team privacy setting: 'O' for a public (open) team, 'I' for a private (invitation only) team" required: true responses: "200": description: Team conversion successful content: application/json: schema: $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/teams/{team_id}/restore: post: tags: - teams summary: Restore a team description: | Restore a team that was previously soft deleted. __Minimum server version__: 5.24 ##### Permissions Must have the `manage_team` permission. operationId: RestoreTeam parameters: - name: team_id in: path description: Team GUID required: true schema: type: string responses: "200": description: Team restore successful content: application/json: schema: $ref: '#/components/schemas/Team' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' /api/v4/teams/name/{name}: get: tags: - teams summary: Get a team by name description: > Get a team based on provided name string ##### Permissions Must be authenticated, team type is open and have the `view_team` permission. operationId: GetTeamByName parameters: - name: name in: path description: Team Name required: true schema: type: string responses: "200": description: Team retrieval successful content: application/json: schema: $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/teams/search: post: tags: - teams summary: Search teams description: | Search teams based on search term and options provided in the request body. ##### Permissions Logged in user only shows open teams Logged in user with "manage_system" permission shows all teams operationId: SearchTeams requestBody: content: application/json: schema: type: object properties: term: description: The search term to match against the name or display name of teams type: string 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. allow_open_invite: type: boolean description: > Filters results to teams where `allow_open_invite` is set to true or false, excludes group constrained channels if this filter option is passed. If this filter option is not passed then the query will remain unchanged. __Minimum server version__: 5.28 group_constrained: type: boolean description: > Filters results to teams where `group_constrained` is set to true or false, returns the union of results when used with `allow_open_invite` If the filter option is not passed then the query will remain unchanged. __Minimum server version__: 5.28 exclude_policy_constrained: type: boolean default: false description: > If set to true, only teams 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 description: Search criteria required: true responses: "200": description: Paginated teams 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 teams.) content: application/json: schema: type: object properties: teams: type: array description: The teams that matched the query. items: $ref: '#/components/schemas/Team' 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' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' /api/v4/teams/name/{name}/exists: get: tags: - teams summary: Check if team exists description: | Check if the team exists based on a team name. ##### Permissions Must be authenticated. operationId: TeamExists parameters: - name: name in: path description: Team Name required: true schema: type: string responses: "200": description: Team retrieval successful content: application/json: schema: $ref: '#/components/schemas/TeamExists' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "404": $ref: '#/components/responses/NotFound' /api/v4/users/{user_id}/teams: get: tags: - teams summary: Get a user's teams description: > Get a list of teams that a user is on. ##### Permissions Must be authenticated as the user or have the `manage_system` permission. operationId: GetTeamsForUser parameters: - name: user_id in: path description: User GUID required: true schema: type: string responses: "200": description: Team list 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' /api/v4/teams/{team_id}/members: get: tags: - teams summary: Get team members description: > Get a page team members list based on query string parameters - team id, page and per page. ##### Permissions Must be authenticated and have the `view_team` permission. operationId: GetTeamMembers 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 users per page. schema: type: integer default: 60 responses: "200": description: Team members retrieval successful content: application/json: schema: type: array items: $ref: '#/components/schemas/TeamMember' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' post: tags: - teams summary: Add user to team description: > Add user to the team by user_id. ##### Permissions Must be authenticated and team be open to add self. For adding another user, authenticated user must have the `add_user_to_team` permission. operationId: AddTeamMember parameters: - name: team_id in: path description: Team GUID required: true schema: type: string requestBody: content: application/json: schema: type: object properties: team_id: type: string user_id: type: string required: true responses: "201": description: Team member creation successful content: application/json: schema: $ref: '#/components/schemas/TeamMember' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' /api/v4/teams/members/invite: post: tags: - teams summary: Add user to team from invite description: > Using either an invite id or hash/data pair from an email invite link, add a user to a team. ##### Permissions Must be authenticated. operationId: AddTeamMemberFromInvite parameters: - name: token in: query description: Token id from the invitation required: true schema: type: string responses: "201": description: Team member creation successful content: application/json: schema: $ref: '#/components/schemas/TeamMember' "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}/members/batch: post: tags: - teams summary: Add multiple users to team description: > Add a number of users to the team by user_id. ##### Permissions Must be authenticated. Authenticated user must have the `add_user_to_team` permission. operationId: AddTeamMembers parameters: - name: team_id in: path description: Team GUID required: true schema: type: string - name: graceful in: query description: 'Instead of aborting the operation if a user cannot be added, return an arrray that will contain both the success and added members and the ones with error, in form of `[{"member": {...}, "user_id", "...", "error": {...}}]`' schema: type: boolean requestBody: content: application/json: schema: type: array items: $ref: '#/components/schemas/TeamMember' required: true responses: "201": description: Team members created successfully. content: application/json: schema: type: array items: $ref: '#/components/schemas/TeamMember' "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/members: get: tags: - teams summary: Get team members for a user description: > Get a list of team members for a user. Useful for getting the ids of teams the user is on and the roles they have in those teams. ##### Permissions Must be logged in as the user or have the `edit_other_users` permission. operationId: GetTeamMembersForUser parameters: - name: user_id in: path description: User GUID required: true schema: type: string responses: "200": description: Team members retrieval successful content: application/json: schema: type: array items: $ref: '#/components/schemas/TeamMember' "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}/members/{user_id}: get: tags: - teams summary: Get a team member description: | Get a team member on the system. ##### Permissions Must be authenticated and have the `view_team` permission. operationId: GetTeamMember 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: Team member retrieval successful content: application/json: schema: $ref: '#/components/schemas/TeamMember' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' delete: tags: - teams summary: Remove user from team description: > Delete the team member object for a user, effectively removing them from a team. ##### Permissions Must be logged in as the user or have the `remove_user_from_team` permission. operationId: RemoveTeamMember 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: Team 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' "404": $ref: '#/components/responses/NotFound' /api/v4/teams/{team_id}/members/ids: post: tags: - teams summary: Get team members by ids description: | Get a list of team members based on a provided array of user ids. ##### Permissions Must have `view_team` permission for the team. operationId: GetTeamMembersByIds 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 user ids required: true responses: "200": description: Team members retrieval successful content: application/json: schema: type: array items: $ref: '#/components/schemas/TeamMember' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' /api/v4/teams/{team_id}/stats: get: tags: - teams summary: Get a team stats description: | Get a team stats on the system. ##### Permissions Must be authenticated and have the `view_team` permission. operationId: GetTeamStats parameters: - name: team_id in: path description: Team GUID required: true schema: type: string responses: "200": description: Team stats retrieval successful content: application/json: schema: $ref: '#/components/schemas/TeamStats' "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}/regenerate_invite_id: post: tags: - teams summary: Regenerate the Invite ID from a Team description: | Regenerates the invite ID used in invite links of a team ##### Permissions Must be authenticated and have the `manage_team` permission. operationId: RegenerateTeamInviteId parameters: - name: team_id in: path description: Team GUID required: true schema: type: string responses: "200": description: Team Invite ID regenerated content: application/json: schema: $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/teams/{team_id}/image: get: tags: - teams summary: Get the team icon description: > Get the team icon of the team. __Minimum server version__: 4.9 ##### Permissions User must be authenticated. In addition, team must be open or the user must have the `view_team` permission. operationId: GetTeamIcon parameters: - name: team_id in: path description: Team GUID required: true schema: type: string responses: "200": description: Team icon retrieval successful "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "501": $ref: '#/components/responses/NotImplemented' post: tags: - teams summary: Sets the team icon description: | Sets the team icon for the team. __Minimum server version__: 4.9 ##### Permissions Must be authenticated and have the `manage_team` permission. operationId: SetTeamIcon parameters: - name: team_id in: path description: Team GUID required: true schema: type: string requestBody: content: multipart/form-data: schema: type: object properties: image: description: The image to be uploaded type: string format: binary required: - image responses: "200": description: Team icon successfully set content: application/json: schema: $ref: '#/components/schemas/StatusOK' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "500": $ref: '#/components/responses/InternalServerError' "501": $ref: '#/components/responses/NotImplemented' delete: tags: - teams summary: Remove the team icon description: | Remove the team icon for the team. __Minimum server version__: 4.10 ##### Permissions Must be authenticated and have the `manage_team` permission. operationId: RemoveTeamIcon parameters: - name: team_id in: path description: Team GUID required: true schema: type: string responses: "200": description: Team icon successfully remove content: application/json: schema: $ref: '#/components/schemas/StatusOK' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "500": $ref: '#/components/responses/InternalServerError' "501": $ref: '#/components/responses/NotImplemented' /api/v4/teams/{team_id}/members/{user_id}/roles: put: tags: - teams summary: Update a team member roles description: > Update a team member roles. Valid team roles are "team_user", "team_admin" or both of them. Overwrites any previously assigned team roles. ##### Permissions Must be authenticated and have the `manage_team_roles` permission. operationId: UpdateTeamMemberRoles 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: object required: - roles properties: roles: type: string description: Space-delimited team roles to assign to the user required: true responses: "200": description: Team member 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' "404": $ref: '#/components/responses/NotFound' /api/v4/teams/{team_id}/members/{user_id}/schemeRoles: put: tags: - teams summary: Update the scheme-derived roles of a team member. description: > Update a team member's scheme_admin/scheme_user properties. Typically this should either be `scheme_admin=false, scheme_user=true` for ordinary team member, or `scheme_admin=true, scheme_user=true` for a team admin. __Minimum server version__: 5.0 ##### Permissions Must be authenticated and have the `manage_team_roles` permission. operationId: UpdateTeamMemberSchemeRoles 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: object required: - scheme_admin - scheme_user properties: scheme_admin: type: boolean scheme_user: type: boolean description: Scheme properties. required: true responses: "200": description: Team 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/users/{user_id}/teams/unread: get: tags: - teams summary: Get team unreads for a user description: > Get the count for unread messages and mentions in the teams the user is a member of. ##### Permissions Must be logged in. operationId: GetTeamsUnreadForUser parameters: - name: user_id in: path description: User GUID required: true schema: type: string - name: exclude_team in: query description: Optional team id to be excluded from the results required: true schema: type: string - name: include_collapsed_threads in: query description: Boolean to determine whether the collapsed threads should be included or not schema: type: boolean default: false responses: "200": description: Team unreads retrieval successful content: application/json: schema: type: array items: $ref: '#/components/schemas/TeamUnread' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' /api/v4/users/{user_id}/teams/{team_id}/unread: get: tags: - teams summary: Get unreads for a team description: > Get the unread mention and message counts for a team for the specified user. ##### Permissions Must be the user or have `edit_other_users` permission and have `view_team` permission for the team. operationId: GetTeamUnread 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: Team unread count retrieval successful content: application/json: schema: $ref: '#/components/schemas/TeamUnread' "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}/invite/email: post: tags: - teams summary: Invite users to the team by email description: | Invite users to the existing team using the user's email. The number of emails that can be sent is rate limited to 20 per hour with a burst of 20 emails. If the rate limit exceeds, the error message contains details on when to retry and when the timer will be reset. ##### Permissions Must have `invite_user` and `add_user_to_team` permissions for the team. operationId: InviteUsersToTeam 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 user's email required: true responses: "200": description: Users invite successful content: application/json: schema: $ref: '#/components/schemas/StatusOK' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "413": $ref: '#/components/responses/TooLarge' /api/v4/teams/{team_id}/invite-guests/email: post: tags: - teams summary: Invite guests to the team by email description: | Invite guests to existing team channels usign the user's email. The number of emails that can be sent is rate limited to 20 per hour with a burst of 20 emails. If the rate limit exceeds, the error message contains details on when to retry and when the timer will be reset. __Minimum server version__: 5.16 ##### Permissions Must have `invite_guest` permission for the team. operationId: InviteGuestsToTeam parameters: - name: team_id in: path description: Team GUID required: true schema: type: string requestBody: content: application/json: schema: type: object required: - emails - channels properties: emails: type: array items: type: string description: List of emails channels: type: array items: type: string description: List of channel ids message: type: string description: Message to include in the invite description: Guests invite information required: true responses: "200": description: Guests invite successful content: application/json: schema: $ref: '#/components/schemas/StatusOK' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "413": $ref: '#/components/responses/TooLarge' /api/v4/teams/invites/email: delete: tags: - teams summary: Invalidate active email invitations description: > Invalidate active email invitations that have not been accepted by the user. ##### Permissions Must have `sysconsole_write_authentication` permission. operationId: InvalidateEmailInvites responses: "200": description: Email invites successfully revoked 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/teams/{team_id}/import: post: tags: - teams summary: Import a Team from other application description: > Import a team into a existing team. Import users, channels, posts, hooks. ##### Permissions Must have `permission_import_team` permission. operationId: ImportTeam parameters: - name: team_id in: path description: Team GUID required: true schema: type: string requestBody: content: multipart/form-data: schema: type: object properties: file: description: A file to be uploaded in zip format. type: string format: binary filesize: description: The size of the zip file to be imported. type: integer importFrom: description: String that defines from which application the team was exported to be imported into Mattermost. type: string required: - file - filesize - importFrom responses: "200": description: JSON object containing a base64 encoded text file of the import logs in its `results` property. content: application/json: schema: type: object properties: results: type: string "400": $ref: '#/components/responses/BadRequest' "403": $ref: '#/components/responses/Forbidden' /api/v4/teams/invite/{invite_id}: get: tags: - teams summary: Get invite info for a team description: > Get the `name`, `display_name`, `description` and `id` for a team from the invite id. __Minimum server version__: 4.0 ##### Permissions No authentication required. operationId: GetTeamInviteInfo parameters: - name: invite_id in: path description: Invite id for a team required: true schema: type: string responses: "200": description: Team invite info retrieval successful content: application/json: schema: type: object properties: id: type: string name: type: string display_name: type: string description: type: string "400": $ref: '#/components/responses/BadRequest' /api/v4/teams/{team_id}/scheme: put: tags: - teams summary: Set a team's scheme description: > Set a team's scheme, more specifically sets the scheme_id value of a team record. ##### Permissions Must have `manage_system` permission. __Minimum server version__: 5.0 operationId: UpdateTeamScheme parameters: - name: team_id in: path description: Team 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 team 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/teams/{team_id}/members_minus_group_members: get: tags: - teams summary: Team members minus group members. description: > Get the set of users who are members of the team 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 team. ##### Permissions Must have `manage_system` permission. __Minimum server version__: 5.14 operationId: TeamMembersMinusGroupMembers parameters: - name: team_id in: path description: Team 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: 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" 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' x-codeSamples: - lang: Go source: | package main import ( "context" "fmt" "log" "os" "github.com/mattermost/mattermost/server/public/model" ) func main() { client := model.NewAPIv4Client(os.Getenv("MM_SERVICESETTINGS_SITEURL")) client.SetToken(os.Getenv("MM_AUTHTOKEN")) channel, _, err := client.CreateChannel(context.Background(), &model.Channel{ Name: "channel_name", DisplayName: "Channel Name", Type: model.ChannelTypeOpen, TeamId: "team_id", }) if err != nil { log.Fatal(err) } fmt.Printf("Created channel with id %s\n", channel.Id) } /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' x-codeSamples: - lang: Go source: | package main import ( "context" "fmt" "log" "os" "github.com/mattermost/mattermost/server/public/model" ) func main() { client := model.NewAPIv4Client(os.Getenv("MM_SERVICESETTINGS_SITEURL")) client.SetToken(os.Getenv("MM_AUTHTOKEN")) userID1 := "user_id_1" userID2 := "user_id_2" channel, _, err := client.CreateDirectChannel(context.Background(), userID1, userID2) if err != nil { log.Fatal(err) } fmt.Printf("Created direct message channel with id %s for users %s and %s\n", channel.Id, userID1, userID2) } /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 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' x-codeSamples: - lang: Go source: | package main import ( "context" "fmt" "log" "os" "github.com/mattermost/mattermost/server/public/model" ) func main() { client := model.NewAPIv4Client(os.Getenv("MM_SERVICESETTINGS_SITEURL")) client.SetToken(os.Getenv("MM_AUTHTOKEN")) userIDs := []string{"user_id_1", "user_id_2", "user_id_3"} channel, _, err := client.CreateGroupChannel(context.Background(), userIDs) if err != nil { log.Fatal(err) } fmt.Printf("Created group message channel with id %s for users %s, %s and %s\n", channel.Id, userIDs[0], userIDs[1], userIDs[2]) } /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. 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 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' x-codeSamples: - lang: Go source: | package main import ( "context" "fmt" "log" "os" "github.com/mattermost/mattermost/server/public/model" ) func main() { client := model.NewAPIv4Client(os.Getenv("MM_SERVICESETTINGS_SITEURL")) client.SetToken(os.Getenv("MM_AUTHTOKEN")) channels, _, err := client.SearchGroupChannels(context.Background(), &model.ChannelSearch{ Term: "member username", }) if err != nil { log.Fatal(err) } fmt.Printf("Found %d channels\n", len(channels)) } /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' x-codeSamples: - lang: Go source: | package main import ( "context" "fmt" "log" "os" "github.com/mattermost/mattermost/server/public/model" ) func main() { client := model.NewAPIv4Client(os.Getenv("MM_SERVICESETTINGS_SITEURL")) client.SetToken(os.Getenv("MM_AUTHTOKEN")) teamId := "team_id" channelIds := []string{"channel_id_1", "channel_id_2"} channels, _, err := client.GetPublicChannelsByIdsForTeam(context.Background(), teamId, channelIds) if err != nil { log.Fatal(err) } fmt.Printf("Found %d channels\n", len(channels)) } /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' x-codeSamples: - lang: Go source: | package main import ( "context" "fmt" "log" "os" "github.com/mattermost/mattermost/server/public/model" ) func main() { client := model.NewAPIv4Client(os.Getenv("MM_SERVICESETTINGS_SITEURL")) client.SetToken(os.Getenv("MM_AUTHTOKEN")) channelId := "channel_id" memberTimezones, _, err := client.GetChannelMembersTimezones(context.Background(), channelId) if err != nil { log.Fatal(err) } fmt.Printf("Found %d timezones used by members of the channel %s\n", len(memberTimezones), channelId) } /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' x-codeSamples: - lang: Go source: | package main import ( "context" "fmt" "log" "os" "github.com/mattermost/mattermost/server/public/model" ) func main() { client := model.NewAPIv4Client(os.Getenv("MM_SERVICESETTINGS_SITEURL")) client.SetToken(os.Getenv("MM_AUTHTOKEN")) channelId := "channel_id" etag := "" channel, _, err := client.GetChannel(context.Background(), channelId, etag) if err != nil { log.Fatal(err) } fmt.Printf("Found channel with name %s\n", channel.Name) } 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' x-codeSamples: - lang: Go source: | package main import ( "context" "log" "os" "github.com/mattermost/mattermost/server/public/model" ) func main() { client := model.NewAPIv4Client(os.Getenv("MM_SERVICESETTINGS_SITEURL")) client.SetToken(os.Getenv("MM_AUTHTOKEN")) channelId := "channel_id" _, err := client.DeleteChannel(context.Background(), channelId) if err != nil { log.Fatal(err) } } /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. The fields that can be updated are defined in the request body, all other provided fields will be ignored. ##### 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: PatchChannel parameters: - name: channel_id in: path description: Channel GUID 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 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 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' x-codeSamples: - lang: Go source: | package main import ( "context" "fmt" "log" "os" "github.com/mattermost/mattermost/server/public/model" ) func main() { client := model.NewAPIv4Client(os.Getenv("MM_SERVICESETTINGS_SITEURL")) client.SetToken(os.Getenv("MM_AUTHTOKEN")) channelId := "channel_id" etag := "" excludeFilesCount := true stats, _, err := client.GetChannelStats(context.Background(), channelId, etag, excludeFilesCount) if err != nil { log.Fatal(err) } fmt.Printf("Found %d members and %d guests in channel %s\n", stats.MemberCount, stats.GuestCount, channelId) } /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' x-codeSamples: - lang: Go source: | package main import ( "context" "fmt" "log" "os" "github.com/mattermost/mattermost/server/public/model" ) func main() { client := model.NewAPIv4Client(os.Getenv("MM_SERVICESETTINGS_SITEURL")) client.SetToken(os.Getenv("MM_AUTHTOKEN")) channelId := "channel_id" etag := "" posts, _, err := client.GetPinnedPosts(context.Background(), channelId, etag) if err != nil { log.Fatal(err) } fmt.Printf("Found %d pinned posts for channel %s\n", len(posts.Posts), channelId) } /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' x-codeSamples: - lang: Go source: | package main import ( "context" "fmt" "log" "os" "github.com/mattermost/mattermost/server/public/model" ) func main() { client := model.NewAPIv4Client(os.Getenv("MM_SERVICESETTINGS_SITEURL")) client.SetToken(os.Getenv("MM_AUTHTOKEN")) teamId := "team_id" page := 0 perPage := 100 etag := "" channels, _, err := client.GetPublicChannelsForTeam(context.Background(), teamId, page, perPage, etag) if err != nil { log.Fatal(err) } fmt.Printf("Found %d public channels for team %s\n", len(channels), teamId) } /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' x-codeSamples: - lang: Go source: | package main import ( "context" "fmt" "log" "os" "github.com/mattermost/mattermost/server/public/model" ) func main() { client := model.NewAPIv4Client(os.Getenv("MM_SERVICESETTINGS_SITEURL")) client.SetToken(os.Getenv("MM_AUTHTOKEN")) teamId := "team_id" page := 0 perPage := 100 etag := "" channels, _, err := client.GetPrivateChannelsForTeam(context.Background(), teamId, page, perPage, etag) if err != nil { log.Fatal(err) } fmt.Printf("Found %d private channels for team %s\n", len(channels), teamId) } /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/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' x-codeSamples: - lang: Go source: | package main import ( "context" "fmt" "log" "os" "github.com/mattermost/mattermost/server/public/model" ) func main() { client := model.NewAPIv4Client(os.Getenv("MM_SERVICESETTINGS_SITEURL")) client.SetToken(os.Getenv("MM_AUTHTOKEN")) teamId := "team_id" searchTerm := "search" channels, _, err := client.SearchChannels(context.Background(), teamId, &model.ChannelSearch{ Term: searchTerm, }) if err != nil { log.Fatal(err) } fmt.Printf("Found %d channels on team %s matching term '%s'\n", len(channels), teamId, searchTerm) } /api/v4/teams/{team_id}/channels/search_archived: post: tags: - channels summary: Search archived channels description: > Search archived channels on a team based on the search term provided in the request body. __Minimum server version__: 5.18 ##### Permissions Must have the `list_team_channels` permission. In server version 5.18 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: SearchArchivedChannels 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 archived 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' x-codeSamples: - lang: Go source: | package main import ( "context" "fmt" "log" "os" "github.com/mattermost/mattermost/server/public/model" ) func main() { client := model.NewAPIv4Client(os.Getenv("MM_SERVICESETTINGS_SITEURL")) client.SetToken(os.Getenv("MM_AUTHTOKEN")) teamId := "team_id" searchTerm := "search" channels, _, err := client.SearchArchivedChannels(context.Background(), teamId, &model.ChannelSearch{ Term: searchTerm, }) if err != nil { log.Fatal(err) } fmt.Printf("Found %d archived channels on team %s matching term '%s'\n", len(channels), teamId, searchTerm) } /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' x-codeSamples: - lang: Go source: | package main import ( "context" "fmt" "log" "os" "github.com/mattermost/mattermost/server/public/model" ) func main() { client := model.NewAPIv4Client(os.Getenv("MM_SERVICESETTINGS_SITEURL")) client.SetToken(os.Getenv("MM_AUTHTOKEN")) channelName := "channel_name" teamId := "team_id" etag := "" channel, _, err := client.GetChannelByName(context.Background(), channelName, teamId, etag) if err != nil { log.Fatal(err) } fmt.Printf("Found channel %s with name %s\n", channel.Id, channel.Name) } /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' x-codeSamples: - lang: Go source: | package main import ( "context" "fmt" "log" "os" "github.com/mattermost/mattermost/server/public/model" ) func main() { client := model.NewAPIv4Client(os.Getenv("MM_SERVICESETTINGS_SITEURL")) client.SetToken(os.Getenv("MM_AUTHTOKEN")) channelName := "channel_name" teamName := "team_name" etag := "" channel, _, err := client.GetChannelByNameForTeamName(context.Background(), channelName, teamName, etag) if err != nil { log.Fatal(err) } fmt.Printf("Found channel %s with name %s\n", channel.Id, channel.Name) } /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. There is a maximum limit of 200 members. 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' x-codeSamples: - lang: Go source: | package main import ( "context" "fmt" "log" "os" "github.com/mattermost/mattermost/server/public/model" ) func main() { client := model.NewAPIv4Client(os.Getenv("MM_SERVICESETTINGS_SITEURL")) client.SetToken(os.Getenv("MM_AUTHTOKEN")) channelId := "channel_id" page := 0 perPage := 60 etag := "" members, _, err := client.GetChannelMembers(context.Background(), channelId, page, perPage, etag) if err != nil { log.Fatal(err) } fmt.Printf("Found %d channel members for channel %s\n", len(members), channelId) } post: tags: - channels summary: Add user to channel description: Add a user to a channel by creating a channel member object. operationId: AddChannelMember parameters: - name: channel_id in: path description: The channel ID required: true schema: type: string requestBody: content: application/json: schema: type: object required: - user_id properties: user_id: type: string description: The ID of user to add into the channel 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' x-codeSamples: - lang: Go source: | package main import ( "context" "fmt" "log" "os" "github.com/mattermost/mattermost/server/public/model" ) func main() { client := model.NewAPIv4Client(os.Getenv("MM_SERVICESETTINGS_SITEURL")) client.SetToken(os.Getenv("MM_AUTHTOKEN")) channelId := "channel_id" userId := "user_id" cm, _, err := client.AddChannelMember(context.Background(), channelId, userId) if err != nil { log.Fatal(err) } fmt.Printf("Added user %s to channel %s with roles %s\n", userId, channelId, cm.Roles) postRootId := "post_root_id" cm, _, err = client.AddChannelMemberWithRootId(context.Background(), channelId, userId, postRootId) if err != nil { log.Fatal(err) } fmt.Printf("Added user %s to channel %s with roles %s using post %s\n", userId, channelId, cm.Roles, postRootId) } /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' x-codeSamples: - lang: Go source: | package main import ( "context" "fmt" "log" "os" "github.com/mattermost/mattermost/server/public/model" ) func main() { client := model.NewAPIv4Client(os.Getenv("MM_SERVICESETTINGS_SITEURL")) client.SetToken(os.Getenv("MM_AUTHTOKEN")) channelId := "channel_id" usersIds := []string{"user_id_1", "user_id_2"} members, _, err := client.GetChannelMembersByIds(context.Background(), channelId, usersIds) if err != nil { log.Fatal(err) } fmt.Printf("Found %d channel members for channel %s\n", len(members), channelId) } /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' x-codeSamples: - lang: Go source: | package main import ( "context" "fmt" "log" "os" "github.com/mattermost/mattermost/server/public/model" ) func main() { client := model.NewAPIv4Client(os.Getenv("MM_SERVICESETTINGS_SITEURL")) client.SetToken(os.Getenv("MM_AUTHTOKEN")) channelId := "channel_id" userId := "user_id" etag := "" member, _, err := client.GetChannelMember(context.Background(), channelId, userId, etag) if err != nil { log.Fatal(err) } fmt.Printf("Found channel member for user %s in channel %s having roles %s\n", userId, channelId, member.Roles) } 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' x-codeSamples: - lang: Go source: | package main import ( "context" "log" "os" "github.com/mattermost/mattermost/server/public/model" ) func main() { client := model.NewAPIv4Client(os.Getenv("MM_SERVICESETTINGS_SITEURL")) client.SetToken(os.Getenv("MM_AUTHTOKEN")) channelId := "channel_id" userId := "user_id" _, err := client.RemoveUserFromChannel(context.Background(), channelId, userId) if err != nil { log.Fatal(err) } } /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/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' x-codeSamples: - lang: Go source: | package main import ( "context" "log" "os" "github.com/mattermost/mattermost/server/public/model" ) func main() { client := model.NewAPIv4Client(os.Getenv("MM_SERVICESETTINGS_SITEURL")) client.SetToken(os.Getenv("MM_AUTHTOKEN")) channelId := "channel_id" prevChannelId := "prev_channel_id" userId := "user_id" _, _, err := client.ViewChannel(context.Background(), userId, &model.ChannelView{ ChannelId: channelId, PrevChannelId: prevChannelId, CollapsedThreadsSupported: true, }) if err != nil { log.Fatal(err) } } /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' x-codeSamples: - lang: Go source: | package main import ( "context" "fmt" "log" "os" "github.com/mattermost/mattermost/server/public/model" ) func main() { client := model.NewAPIv4Client(os.Getenv("MM_SERVICESETTINGS_SITEURL")) client.SetToken(os.Getenv("MM_AUTHTOKEN")) userId := "user_id" teamId := "team_id" etag := "" members, _, err := client.GetChannelMembersForUser(context.Background(), userId, teamId, etag) if err != nil { log.Fatal(err) } fmt.Printf("Found %d channel members for user %s on team %s\n", len(members), userId, teamId) } /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' x-codeSamples: - lang: Go source: | package main import ( "context" "fmt" "log" "os" "github.com/mattermost/mattermost/server/public/model" ) func main() { client := model.NewAPIv4Client(os.Getenv("MM_SERVICESETTINGS_SITEURL")) client.SetToken(os.Getenv("MM_AUTHTOKEN")) userId := "user_id" teamId := "team_id" includeDeleted := false etag := "" channels, _, err := client.GetChannelsForTeamForUser(context.Background(), teamId, userId, includeDeleted, etag) if err != nil { log.Fatal(err) } fmt.Printf("Found %d channels for user %s on team %s\n", len(channels), userId, teamId) } /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' x-codeSamples: - lang: Go source: | package main import ( "context" "fmt" "log" "os" "github.com/mattermost/mattermost/server/public/model" ) func main() { client := model.NewAPIv4Client(os.Getenv("MM_SERVICESETTINGS_SITEURL")) client.SetToken(os.Getenv("MM_AUTHTOKEN")) channelId := "channel_id" userId := "user_id" channelUnread, _, err := client.GetChannelUnread(context.Background(), channelId, userId) if err != nil { log.Fatal(err) } fmt.Printf("Found %d unread messages with %d mentions for user %s in channel %s\n", channelUnread.MentionCount, channelUnread.MentionCount, userId, channelId) } /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/posts: post: tags: - posts summary: Create a post description: > Create a new post in a channel. To create the post as a comment on another post, provide `root_id`. ##### Permissions Must have `create_post` permission for the channel the post is being created in. operationId: CreatePost parameters: - name: set_online in: query description: Whether to set the user status as online or not. schema: type: boolean requestBody: content: application/json: schema: type: object required: - channel_id - message properties: channel_id: type: string description: The channel ID to post in message: type: string description: The message contents, can be formatted with Markdown root_id: type: string description: The post ID to comment on file_ids: type: array description: A list of file IDs to associate with the post. Note that posts are limited to 5 files maximum. Please use additional posts for more files. items: type: string props: description: A general JSON property bag to attach to the post type: object metadata: description: A JSON object to add post metadata, e.g the post's priority type: object properties: priority: type: object description: An object containing the post's priority properties properties: priority: type: string description: The priority label of the post, could empty, important, or urgent requested_ack: type: boolean description: Set to true to request for acknowledgements description: Post object to create required: true responses: "201": description: Post creation successful content: application/json: schema: $ref: '#/components/schemas/Post' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' /api/v4/posts/ephemeral: post: tags: - posts summary: Create a ephemeral post description: > Create a new ephemeral post in a channel. ##### Permissions Must have `create_post_ephemeral` permission (currently only given to system admin) operationId: CreatePostEphemeral requestBody: content: application/json: schema: type: object required: - user_id - post properties: user_id: type: string description: The target user id for the ephemeral post post: type: object required: - channel_id - message description: Post object to create properties: channel_id: type: string description: The channel ID to post in message: type: string description: The message contents, can be formatted with Markdown description: Ephemeral Post object to send required: true responses: "201": description: Post creation successful content: application/json: schema: $ref: '#/components/schemas/Post' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' /api/v4/posts/{post_id}: get: tags: - posts summary: Get a post description: > Get a single post. ##### Permissions Must have `read_channel` permission for the channel the post is in or if the channel is public, have the `read_public_channels` permission for the team. operationId: GetPost parameters: - name: post_id in: path description: ID of the post to get required: true schema: type: string - name: include_deleted in: query description: Defines if result should include deleted posts, must have 'manage_system' (admin) permission. schema: type: boolean default: false responses: "200": description: Post retrieval successful headers: Has-Inaccessible-Posts: schema: type: boolean description: This header is included with the value "true" if the post is past the cloud's plan limit. content: application/json: schema: $ref: '#/components/schemas/Post' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' delete: tags: - posts summary: Delete a post description: > Soft deletes a post, by marking the post as deleted in the database. Soft deleted posts will not be returned in post queries. ##### Permissions Must be logged in as the user or have `delete_others_posts` permission. operationId: DeletePost parameters: - name: post_id in: path description: ID of the post to delete required: true schema: type: string responses: "200": description: Post 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' put: tags: - posts summary: Update a post description: > Update a post. Only the fields listed below are updatable, omitted fields will be treated as blank. ##### Permissions Must have `edit_post` permission for the channel the post is in. operationId: UpdatePost parameters: - name: post_id in: path description: ID of the post to update required: true schema: type: string requestBody: content: application/json: schema: type: object required: - id properties: id: description: ID of the post to update type: string is_pinned: description: Set to `true` to pin the post to the channel it is in type: boolean message: description: The message text of the post type: string has_reactions: description: Set to `true` if the post has reactions to it type: boolean props: description: A general JSON property bag to attach to the post type: string description: Post object that is to be updated required: true responses: "200": description: Post update successful content: application/json: schema: $ref: '#/components/schemas/Post' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' /api/v4/users/{user_id}/posts/{post_id}/set_unread: post: tags: - posts summary: Mark as unread from a post. description: > Mark a channel as being unread from a given post. ##### Permissions Must have `read_channel` permission for the channel the post is in or if the channel is public, have the `read_public_channels` permission for the team. Must have `edit_other_users` permission if the user is not the one marking the post for himself. __Minimum server version__: 5.18 operationId: SetPostUnread parameters: - name: user_id in: path description: User GUID required: true schema: type: string - name: post_id in: path description: Post GUID required: true schema: type: string responses: "200": description: Post marked as unread successfully content: application/json: schema: $ref: '#/components/schemas/ChannelUnreadAt' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' /api/v4/posts/{post_id}/patch: put: tags: - posts summary: Patch a post description: > Partially update a post by providing only the fields you want to update. Omitted fields will not be updated. The fields that can be updated are defined in the request body, all other provided fields will be ignored. ##### Permissions Must have the `edit_post` permission. operationId: PatchPost parameters: - name: post_id in: path description: Post GUID required: true schema: type: string requestBody: content: application/json: schema: type: object properties: is_pinned: description: Set to `true` to pin the post to the channel it is in type: boolean message: description: The message text of the post type: string file_ids: description: The list of files attached to this post type: array items: type: string has_reactions: description: Set to `true` if the post has reactions to it type: boolean props: description: A general JSON property bag to attach to the post type: string description: Post object that is to be updated required: true responses: "200": description: Post patch successful content: application/json: schema: $ref: '#/components/schemas/Post' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' /api/v4/posts/{post_id}/thread: get: tags: - posts summary: Get a thread description: > Get a post and the rest of the posts in the same thread. ##### Permissions Must have `read_channel` permission for the channel the post is in or if the channel is public, have the `read_public_channels` permission for the team. operationId: GetPostThread parameters: - name: post_id in: path description: ID of a post in the thread required: true schema: type: string - name: perPage in: query description: The number of posts per page schema: type: integer default: 0 - name: fromPost in: query description: The post_id to return the next page of posts from schema: type: string default: "" - name: fromCreateAt in: query description: The create_at timestamp to return the next page of posts from schema: type: integer default: 0 - name: direction in: query description: The direction to return the posts. Either up or down. schema: type: string default: "" - name: skipFetchThreads in: query description: Whether to skip fetching threads or not schema: type: boolean default: false - name: collapsedThreads in: query description: Whether the client uses CRT or not schema: type: boolean default: false - name: collapsedThreadsExtended in: query description: Whether to return the associated users as part of the response or not schema: type: boolean default: false responses: "200": description: Post list retrieval successful 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/users/{user_id}/posts/flagged: get: tags: - posts summary: Get a list of flagged posts description: > Get a page of flagged posts of a user provided user id string. Selects from a channel, team, or all flagged posts by a user. Will only return posts from channels in which the user is member. ##### Permissions Must be user or have `manage_system` permission. operationId: GetFlaggedPostsForUser parameters: - name: user_id in: path description: ID of the user required: true schema: type: string - name: team_id in: query description: Team ID schema: type: string - name: channel_id in: query description: Channel ID 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 posts per page schema: type: integer default: 60 responses: "200": description: Post list retrieval successful content: application/json: schema: type: array items: $ref: '#/components/schemas/PostList' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' /api/v4/posts/{post_id}/files/info: get: tags: - posts summary: Get file info for post description: > Gets a list of file information objects for the files attached to a post. ##### Permissions Must have `read_channel` permission for the channel the post is in. operationId: GetFileInfosForPost parameters: - name: post_id in: path description: ID of the post required: true schema: type: string - name: include_deleted in: query description: Defines if result should include deleted posts, must have 'manage_system' (admin) permission. schema: type: boolean default: false responses: "200": description: File info retrieval successful content: application/json: schema: type: array items: $ref: '#/components/schemas/FileInfo' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' /api/v4/channels/{channel_id}/posts: get: tags: - posts summary: Get posts for a channel description: > Get a page of posts in a channel. Use the query parameters to modify the behaviour of this endpoint. The parameter `since` must not be used with any of `before`, `after`, `page`, and `per_page` parameters. If `since` is used, it will always return all posts modified since that time, ordered by their create time limited till 1000. A caveat with this parameter is that there is no guarantee that the returned posts will be consecutive. It is left to the clients to maintain state and fill any missing holes in the post order. ##### Permissions Must have `read_channel` permission for the channel. operationId: GetPostsForChannel parameters: - name: channel_id in: path description: The channel ID to get the posts for 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 posts per page schema: type: integer default: 60 - name: since in: query description: Provide a non-zero value in Unix time milliseconds to select posts modified after that time schema: type: integer - name: before in: query description: A post id to select the posts that came before this one schema: type: string - name: after in: query description: A post id to select the posts that came after this one schema: type: string - name: include_deleted in: query description: Whether to include deleted posts or not. Must have system admin permissions. schema: type: boolean default: false responses: "200": description: Post list retrieval successful 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/users/{user_id}/channels/{channel_id}/posts/unread: get: tags: - posts summary: Get posts around oldest unread description: > Get the oldest unread post in the channel for the given user as well as the posts around it. The returned list is sorted in descending order (most recent post first). ##### Permissions Must be logged in as the user or have `edit_other_users` permission, and must have `read_channel` permission for the channel. __Minimum server version__: 5.14 operationId: GetPostsAroundLastUnread parameters: - name: user_id in: path description: ID of the user required: true schema: type: string - name: channel_id in: path description: The channel ID to get the posts for required: true schema: type: string - name: limit_before in: query description: Number of posts before the oldest unread posts. Maximum is 200 posts if limit is set greater than that. schema: type: integer default: 60 maximum: !!float 200 - name: limit_after in: query description: Number of posts after and including the oldest unread post. Maximum is 200 posts if limit is set greater than that. schema: type: integer default: 60 maximum: !!float 200 minimum: !!float 1 - name: skipFetchThreads in: query description: Whether to skip fetching threads or not schema: type: boolean default: false - name: collapsedThreads in: query description: Whether the client uses CRT or not schema: type: boolean default: false - name: collapsedThreadsExtended in: query description: Whether to return the associated users as part of the response or not schema: type: boolean default: false responses: "200": description: Post list retrieval successful 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}/posts/search: post: tags: - posts summary: Search for team posts description: | Search posts in the team and from the provided terms string. ##### Permissions Must be authenticated and have the `view_team` permission. operationId: SearchPosts parameters: - name: team_id in: path description: Team GUID required: true schema: type: string requestBody: content: application/json: schema: type: object required: - terms - is_or_search properties: terms: type: string description: The search terms as inputed by the user. To search for posts from a user include `from:someusername`, using a user's username. To search in a specific channel include `in:somechannel`, using the channel name (not the display name). is_or_search: type: boolean description: Set to true if an Or search should be performed vs an And search. time_zone_offset: type: integer default: 0 description: Offset from UTC of user timezone for date searches. include_deleted_channels: type: boolean description: Set to true if deleted channels should be included in the search. (archived channels) page: type: integer default: 0 description: The page to select. (Only works with Elasticsearch) per_page: type: integer default: 60 description: The number of posts per page. (Only works with Elasticsearch) description: The search terms and logic to use in the search. required: true responses: "200": description: Post list retrieval successful content: application/json: schema: $ref: '#/components/schemas/PostListWithSearchMatches' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' /api/v4/posts/{post_id}/pin: post: tags: - posts summary: Pin a post to the channel description: > Pin a post to a channel it is in based from the provided post id string. ##### Permissions Must be authenticated and have the `read_channel` permission to the channel the post is in. operationId: PinPost parameters: - name: post_id in: path description: Post GUID required: true schema: type: string responses: "200": description: Pinned post 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/posts/{post_id}/unpin: post: tags: - posts summary: Unpin a post to the channel description: > Unpin a post to a channel it is in based from the provided post id string. ##### Permissions Must be authenticated and have the `read_channel` permission to the channel the post is in. operationId: UnpinPost parameters: - name: post_id in: path description: Post GUID required: true schema: type: string responses: "200": description: Unpinned post 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/posts/{post_id}/actions/{action_id}: post: tags: - posts summary: Perform a post action description: > Perform a post action, which allows users to interact with integrations through posts. ##### Permissions Must be authenticated and have the `read_channel` permission to the channel the post is in. operationId: DoPostAction parameters: - name: post_id in: path description: Post GUID required: true schema: type: string - name: action_id in: path description: Action GUID required: true schema: type: string responses: "200": description: Post action 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/posts/ids: post: tags: - posts summary: Get posts by a list of ids description: > Fetch a list of posts based on the provided postIDs ##### Permissions Must have `read_channel` permission for the channel the post is in or if the channel is public, have the `read_public_channels` permission for the team. operationId: getPostsByIds requestBody: content: application/json: schema: type: array items: type: string description: List of post ids required: true responses: "200": description: Post list retrieval successful headers: Has-Inaccessible-Posts: schema: type: boolean description: Indicates whether the posts have been truncated as per the cloud's plan limit. content: application/json: schema: type: array items: $ref: '#/components/schemas/Post' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' /api/v4/users/{user_id}/posts/{post_id}/reminder: post: tags: - posts summary: Set a post reminder description: > Set a reminder for the user for the post. ##### Permissions Must have `read_channel` permission for the channel the post is in. __Minimum server version__: 7.2 operationId: SetPostReminder parameters: - name: user_id in: path description: User GUID required: true schema: type: string - name: post_id in: path description: Post GUID required: true schema: type: string requestBody: content: application/json: schema: type: object required: - target_time properties: target_time: type: integer description: Target time for the reminder description: Target time for the reminder required: true responses: "200": description: Reminder set 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/users/{user_id}/posts/{post_id}/ack: post: tags: - posts summary: Acknowledge a post description: > Acknowledge a post that has a request for acknowledgements. ##### Permissions Must have `read_channel` permission for the channel the post is in.
Must be logged in as the user or have `edit_other_users` permission. __Minimum server version__: 7.7 operationId: SaveAcknowledgementForPost parameters: - name: user_id in: path description: User GUID required: true schema: type: string - name: post_id in: path description: Post GUID required: true schema: type: string responses: "200": description: Acknowledgement saved successfully content: application/json: schema: $ref: '#/components/schemas/PostAcknowledgement' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' delete: tags: - posts summary: Delete a post acknowledgement description: > Delete an acknowledgement form a post that you had previously acknowledged. ##### Permissions Must have `read_channel` permission for the channel the post is in.
Must be logged in as the user or have `edit_other_users` permission.
The post must have been acknowledged in the previous 5 minutes. __Minimum server version__: 7.7 operationId: DeleteAcknowledgementForPost parameters: - name: user_id in: path description: User GUID required: true schema: type: string - name: post_id in: path description: Post GUID required: true schema: type: string responses: "200": description: Acknowledgement deleted 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/posts/{post_id}/move: post: tags: - posts summary: Move a post (and any posts within that post's thread) description: "Move a post/thread to another channel. \nTHIS IS A BETA FEATURE. The API is subject to change without notice.\n##### Permissions\nMust have `read_channel` permission for the channel the post is in. Must have `write_post` permission for the channel the post is being moved to.\n\n__Minimum server version__: 9.3\n" operationId: MoveThread parameters: - name: post_id in: path description: The identifier of the post to move required: true schema: type: string requestBody: content: application/json: schema: type: object required: - channel_id properties: channel_id: type: string description: The channel identifier of where the post/thread is to be moved description: The channel identifier of where the post/thread is to be moved required: true responses: "200": description: Post moved 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' "501": $ref: '#/components/responses/NotImplemented' /api/v4/users/{user_id}/preferences: get: tags: - preferences summary: Get the user's preferences description: > Get a list of the user's preferences. ##### Permissions Must be logged in as the user being updated or have the `edit_other_users` permission. operationId: GetPreferences parameters: - name: user_id in: path description: User GUID required: true schema: type: string responses: "200": description: User preferences retrieval successful content: application/json: schema: type: array items: $ref: '#/components/schemas/Preference' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' put: tags: - preferences summary: Save the user's preferences description: > Save a list of the user's preferences. ##### Permissions Must be logged in as the user being updated or have the `edit_other_users` permission. operationId: UpdatePreferences parameters: - name: user_id in: path description: User GUID required: true schema: type: string requestBody: description: List of preference objects required: true content: application/json: schema: type: array items: $ref: '#/components/schemas/Preference' minItems: 1 maxItems: 100 responses: "200": description: User preferences saved 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/users/{user_id}/preferences/delete: post: tags: - preferences summary: Delete user's preferences description: > Delete a list of the user's preferences. ##### Permissions Must be logged in as the user being updated or have the `edit_other_users` permission. operationId: DeletePreferences parameters: - name: user_id in: path description: User GUID required: true schema: type: string requestBody: description: List of preference objects required: true content: application/json: schema: type: array items: $ref: '#/components/schemas/Preference' minItems: 1 maxItems: 100 responses: "200": description: User preferences saved 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/users/{user_id}/preferences/{category}: get: tags: - preferences summary: List a user's preferences by category description: > Lists the current user's stored preferences in the given category. ##### Permissions Must be logged in as the user being updated or have the `edit_other_users` permission. operationId: GetPreferencesByCategory parameters: - name: user_id in: path description: User GUID required: true schema: type: string - name: category in: path description: The category of a group of preferences required: true schema: type: string responses: "200": description: A list of all of the current user's preferences in the given category content: application/json: schema: type: array items: $ref: '#/components/schemas/Preference' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' /api/v4/users/{user_id}/preferences/{category}/name/{preference_name}: get: tags: - preferences summary: Get a specific user preference description: > Gets a single preference for the current user with the given category and name. ##### Permissions Must be logged in as the user being updated or have the `edit_other_users` permission. operationId: GetPreferencesByCategoryByName parameters: - name: user_id in: path description: User GUID required: true schema: type: string - name: category in: path description: The category of a group of preferences required: true schema: type: string - name: preference_name in: path description: The name of the preference required: true schema: type: string responses: "200": description: > A single preference for the current user in the current categorylist of all of the current user's preferences in the given category. content: application/json: schema: $ref: '#/components/schemas/Preference' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' /api/v4/files: post: tags: - files summary: Upload a file description: > Uploads a file that can later be attached to a post. This request can either be a multipart/form-data request with a channel_id, files and optional client_ids defined in the FormData, or it can be a request with the channel_id and filename defined as query parameters with the contents of a single file in the body of the request. Only multipart/form-data requests are supported by server versions up to and including 4.7. Server versions 4.8 and higher support both types of requests. __Minimum server version__: 9.4 Starting with server version 9.4 when uploading a file for a channel bookmark, the bookmark=true query parameter should be included in the query string ##### Permissions Must have `upload_file` permission. operationId: UploadFile parameters: - name: channel_id in: query description: The ID of the channel that this file will be uploaded to schema: type: string - name: filename in: query description: The name of the file to be uploaded schema: type: string requestBody: content: multipart/form-data: schema: type: object properties: files: description: A file to be uploaded type: string format: binary channel_id: description: The ID of the channel that this file will be uploaded to type: string client_ids: description: A unique identifier for the file that will be returned in the response type: string responses: "201": description: Corresponding lists of the provided client_ids and the metadata that has been stored in the database for each one content: application/json: schema: type: object properties: file_infos: description: A list of file metadata that has been stored in the database type: array items: $ref: '#/components/schemas/FileInfo' client_ids: description: A list of the client_ids that were provided in the request type: array items: type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "413": $ref: '#/components/responses/TooLarge' "501": $ref: '#/components/responses/NotImplemented' /api/v4/files/{file_id}: get: tags: - files summary: Get a file description: | Gets a file that has been uploaded previously. ##### Permissions Must have `read_channel` permission or be uploader of the file. operationId: GetFile parameters: - name: file_id in: path description: The ID of the file to get required: true schema: type: string responses: "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": description: Do not have appropriate permissions content: application/json: schema: $ref: '#/components/schemas/AppError' headers: First-Inaccessible-File-Time: schema: type: integer description: This header is included with the value "1" if the file is past the cloud's plan limit. "404": $ref: '#/components/responses/NotFound' "501": $ref: '#/components/responses/NotImplemented' /api/v4/files/{file_id}/thumbnail: get: tags: - files summary: Get a file's thumbnail description: | Gets a file's thumbnail. ##### Permissions Must have `read_channel` permission or be uploader of the file. operationId: GetFileThumbnail parameters: - name: file_id in: path description: The ID of the file to get required: true schema: type: string responses: "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": description: Do not have appropriate permissions content: application/json: schema: $ref: '#/components/schemas/AppError' headers: First-Inaccessible-File-Time: schema: type: integer description: This header is included with the value "1" if the file is past the cloud's plan limit. "404": $ref: '#/components/responses/NotFound' "501": $ref: '#/components/responses/NotImplemented' /api/v4/files/{file_id}/preview: get: tags: - files summary: Get a file's preview description: | Gets a file's preview. ##### Permissions Must have `read_channel` permission or be uploader of the file. operationId: GetFilePreview parameters: - name: file_id in: path description: The ID of the file to get required: true schema: type: string responses: "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": description: Do not have appropriate permissions content: application/json: schema: $ref: '#/components/schemas/AppError' headers: First-Inaccessible-File-Time: schema: type: integer description: This header is included with the value "1" if the file is past the cloud's plan limit. "404": $ref: '#/components/responses/NotFound' "501": $ref: '#/components/responses/NotImplemented' /api/v4/files/{file_id}/link: get: tags: - files summary: Get a public file link description: > Gets a public link for a file that can be accessed without logging into Mattermost. ##### Permissions Must have `read_channel` permission or be uploader of the file. operationId: GetFileLink parameters: - name: file_id in: path description: The ID of the file to get a link for required: true schema: type: string responses: "200": description: A publicly accessible link to the given file content: application/json: schema: type: object properties: link: type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": description: Do not have appropriate permissions content: application/json: schema: $ref: '#/components/schemas/AppError' headers: First-Inaccessible-File-Time: schema: type: integer description: This header is included with the value "1" if the file is past the cloud's plan limit. "404": $ref: '#/components/responses/NotFound' "501": $ref: '#/components/responses/NotImplemented' /api/v4/files/{file_id}/info: get: tags: - files summary: Get metadata for a file description: | Gets a file's info. ##### Permissions Must have `read_channel` permission or be uploader of the file. operationId: GetFileInfo parameters: - name: file_id in: path description: The ID of the file info to get required: true schema: type: string responses: "200": description: The stored metadata for the given file content: application/json: schema: $ref: '#/components/schemas/FileInfo' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": description: Do not have appropriate permissions content: application/json: schema: $ref: '#/components/schemas/AppError' headers: First-Inaccessible-File-Time: schema: type: integer description: This header is included with the value "1" if the file is past the cloud's plan limit. "404": $ref: '#/components/responses/NotFound' "501": $ref: '#/components/responses/NotImplemented' /files/{file_id}/public: get: tags: - files summary: Get a public file description: | ##### Permissions No permissions required. operationId: GetFilePublic parameters: - name: file_id in: path description: The ID of the file to get required: true schema: type: string - name: h in: query description: File hash required: true schema: type: string responses: "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": description: Do not have appropriate permissions content: application/json: schema: $ref: '#/components/schemas/AppError' headers: First-Inaccessible-File-Time: schema: type: integer description: This header is included with the value "1" if the file is past the cloud's plan limit. "404": $ref: '#/components/responses/NotFound' "501": $ref: '#/components/responses/NotImplemented' /api/v4/teams/{team_id}/files/search: post: tags: - teams - files - search summary: Search files in a team description: > Search for files in a team based on file name, extention and file content (if file content extraction is enabled and supported for the files). __Minimum server version__: 5.34 ##### Permissions Must be authenticated and have the `view_team` permission. operationId: SearchFiles parameters: - name: team_id in: path description: Team GUID required: true schema: type: string requestBody: content: multipart/form-data: schema: type: object required: - terms - is_or_search properties: terms: type: string description: The search terms as inputed by the user. To search for files from a user include `from:someusername`, using a user's username. To search in a specific channel include `in:somechannel`, using the channel name (not the display name). To search for specific extensions included `ext:extension`. is_or_search: type: boolean description: Set to true if an Or search should be performed vs an And search. time_zone_offset: type: integer default: 0 description: Offset from UTC of user timezone for date searches. include_deleted_channels: type: boolean description: Set to true if deleted channels should be included in the search. (archived channels) page: type: integer default: 0 description: The page to select. (Only works with Elasticsearch) per_page: type: integer default: 60 description: The number of posts per page. (Only works with Elasticsearch) description: The search terms and logic to use in the search. required: true responses: "200": description: Files list retrieval successful content: application/json: schema: $ref: '#/components/schemas/FileInfoList' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' /api/v4/uploads: post: tags: - uploads summary: Create an upload description: > Creates a new upload session. __Minimum server version__: 5.28 ##### Permissions Must have `upload_file` permission. operationId: CreateUpload requestBody: content: application/json: schema: type: object required: - channel_id - filename - file_size properties: channel_id: description: The ID of the channel to upload to. type: string filename: description: The name of the file to upload. type: string file_size: description: The size of the file to upload in bytes. type: integer format: int64 required: true responses: "201": description: Upload creation successful. content: application/json: schema: $ref: '#/components/schemas/UploadSession' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "413": $ref: '#/components/responses/TooLarge' "501": $ref: '#/components/responses/NotImplemented' /api/v4/uploads/{upload_id}: get: tags: - uploads summary: Get an upload session description: | Gets an upload session that has been previously created. ##### Permissions Must be logged in as the user who created the upload session. operationId: GetUpload parameters: - name: upload_id in: path description: The ID of the upload session to get. required: true schema: type: string responses: "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "501": $ref: '#/components/responses/NotImplemented' post: tags: - uploads summary: Perform a file upload description: "Starts or resumes a file upload. \nTo resume an existing (incomplete) upload, data should be sent starting from the offset specified in the upload session object.\n\nThe request body can be in one of two formats:\n- Binary file content streamed in request's body\n- multipart/form-data\n\n##### Permissions\nMust be logged in as the user who created the upload session.\n" operationId: UploadData parameters: - name: upload_id in: path description: The ID of the upload session the data belongs to. required: true schema: type: string requestBody: content: application/x-www-form-urlencoded: schema: type: object responses: "201": description: Upload successful content: application/json: schema: $ref: '#/components/schemas/FileInfo' "204": description: Upload incomplete "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "413": $ref: '#/components/responses/TooLarge' "501": $ref: '#/components/responses/NotImplemented' /api/v4/jobs: get: tags: - jobs summary: Get the jobs. description: > Get a page of jobs. Use the query parameters to modify the behaviour of this endpoint. __Minimum server version: 4.1__ ##### Permissions Must have `manage_jobs` permission. operationId: GetJobs parameters: - name: page in: query description: The page to select. schema: type: integer default: 0 - name: per_page in: query description: The number of jobs per page. schema: type: integer default: 60 responses: "200": description: Job list retrieval successful content: application/json: schema: type: array items: $ref: '#/components/schemas/Job' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' post: tags: - jobs summary: Create a new job. description: | Create a new job. __Minimum server version: 4.1__ ##### Permissions Must have `manage_jobs` permission. operationId: CreateJob requestBody: content: application/json: schema: type: object required: - type properties: type: type: string description: The type of job to create data: type: object description: An object containing any additional data required for this job type description: Job object to be created required: true responses: "201": description: Job creation successful content: application/json: schema: $ref: '#/components/schemas/Job' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' /api/v4/jobs/{job_id}: get: tags: - jobs summary: Get a job. description: | Gets a single job. __Minimum server version: 4.1__ ##### Permissions Must have `manage_jobs` permission. operationId: GetJob parameters: - name: job_id in: path description: Job GUID required: true schema: type: string responses: "200": description: Job retrieval successful content: application/json: schema: $ref: '#/components/schemas/Job' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' /api/v4/jobs/{job_id}/download: get: tags: - jobs summary: Download the results of a job. description: | Download the result of a single job. __Minimum server version: 5.28__ ##### Permissions Must have `manage_jobs` permission. operationId: DownloadJob parameters: - name: job_id in: path description: Job GUID required: true schema: type: string responses: "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' /api/v4/jobs/{job_id}/cancel: post: tags: - jobs summary: Cancel a job. description: | Cancel a job. __Minimum server version: 4.1__ ##### Permissions Must have `manage_jobs` permission. operationId: CancelJob parameters: - name: job_id in: path description: Job GUID required: true schema: type: string responses: "200": description: Job canceled 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/jobs/type/{type}: get: tags: - jobs summary: Get the jobs of the given type. description: > Get a page of jobs of the given type. Use the query parameters to modify the behaviour of this endpoint. __Minimum server version: 4.1__ ##### Permissions Must have `manage_jobs` permission. operationId: GetJobsByType parameters: - name: type in: path description: Job type 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 jobs per page. schema: type: integer default: 60 responses: "200": description: Job list retrieval successful content: application/json: schema: type: array items: $ref: '#/components/schemas/Job' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' /api/v4/system/timezones: get: tags: - system summary: Retrieve a list of supported timezones description: > __Minimum server version__: 3.10 ##### Permissions Must be logged in. operationId: GetSupportedTimezone responses: "200": description: List of timezones retrieval successful content: application/json: schema: type: array items: type: string "500": $ref: '#/components/responses/InternalServerError' /api/v4/system/ping: get: tags: - system summary: Check system health description: > Check if the server is up and healthy based on the configuration setting `GoRoutineHealthThreshold`. If `GoRoutineHealthThreshold` and the number of goroutines on the server exceeds that threshold the server is considered unhealthy. If `GoRoutineHealthThreshold` is not set or the number of goroutines is below the threshold the server is considered healthy. __Minimum server version__: 3.10 If a "device_id" is passed in the query, it will test the Push Notification Proxy in order to discover whether the device is able to receive notifications. The response will have a "CanReceiveNotifications" property with one of the following values: - true: It can receive notifications - false: It cannot receive notifications - unknown: There has been an unknown error, and it is not certain whether it can receive notifications. __Minimum server version__: 6.5 If "use_rest_semantics" is set to true in the query, the endpoint will not return an error status code in the header if the request is somehow completed successfully. __Minimum server version__: 9.6 ##### Permissions None. operationId: GetPing parameters: - name: get_server_status in: query description: Check the status of the database and file storage as well schema: type: boolean - name: device_id in: query description: Check whether this device id can receive push notifications schema: type: string - name: use_rest_semantics in: query description: Returns 200 status code even if the server status is unhealthy. schema: type: boolean responses: "200": description: Status of the system content: application/json: schema: $ref: '#/components/schemas/SystemStatusResponse' "500": $ref: '#/components/responses/InternalServerError' /api/v4/system/notices/{teamId}: get: tags: - system summary: Get notices for logged in user in specified team description: > Will return appropriate product notices for current user in the team specified by teamId parameter. __Minimum server version__: 5.26 ##### Permissions Must be logged in. operationId: GetNotices parameters: - name: clientVersion in: query description: Version of the client (desktop/mobile/web) that issues the request required: true schema: type: string - name: locale in: query description: Client locale schema: type: string - name: client in: query description: Client type (web/mobile-ios/mobile-android/desktop) required: true schema: type: string - name: teamId in: path description: ID of the team required: true schema: type: string responses: "200": description: List notices retrieve successful content: application/json: schema: type: array items: $ref: '#/components/schemas/Notice' "500": $ref: '#/components/responses/InternalServerError' /api/v4/system/notices/view: put: tags: - system summary: Update notices as 'viewed' description: > Will mark the specified notices as 'viewed' by the logged in user. __Minimum server version__: 5.26 ##### Permissions Must be logged in. operationId: MarkNoticesViewed requestBody: content: application/json: schema: type: array items: type: string description: Array of notice IDs required: true responses: "200": description: Update successfull content: application/json: schema: $ref: '#/components/schemas/StatusOK' "500": $ref: '#/components/responses/InternalServerError' /api/v4/database/recycle: post: tags: - system summary: Recycle database connections description: > Recycle database connections by closing and reconnecting all connections to master and read replica databases. ##### Permissions Must have `manage_system` permission. operationId: DatabaseRecycle responses: "200": description: Database recycle successful content: application/json: schema: $ref: '#/components/schemas/StatusOK' "403": $ref: '#/components/responses/Forbidden' /api/v4/email/test: post: tags: - system summary: Send a test email description: > Send a test email to make sure you have your email settings configured correctly. Optionally provide a configuration in the request body to test. If no valid configuration is present in the request body the current server configuration will be tested. ##### Permissions Must have `manage_system` permission. operationId: TestEmail requestBody: description: Mattermost configuration required: true content: application/json: schema: $ref: '#/components/schemas/Config' responses: "200": description: Email successful sent content: application/json: schema: $ref: '#/components/schemas/StatusOK' "403": $ref: '#/components/responses/Forbidden' "500": $ref: '#/components/responses/InternalServerError' /api/v4/site_url/test: post: tags: - system summary: Checks the validity of a Site URL description: > Sends a Ping request to the mattermost server using the specified Site URL. ##### Permissions Must have `manage_system` permission. __Minimum server version__: 5.16 operationId: TestSiteURL requestBody: content: application/json: schema: type: object required: - site_url properties: site_url: type: string description: The Site URL to test required: true responses: "200": description: Site URL is valid content: application/json: schema: $ref: '#/components/schemas/StatusOK' "400": $ref: '#/components/responses/BadRequest' "403": $ref: '#/components/responses/Forbidden' "500": $ref: '#/components/responses/InternalServerError' /api/v4/file/s3_test: post: tags: - system summary: Test AWS S3 connection description: > Send a test to validate if can connect to AWS S3. Optionally provide a configuration in the request body to test. If no valid configuration is present in the request body the current server configuration will be tested. ##### Permissions Must have `manage_system` permission. __Minimum server version__: 4.8 operationId: TestS3Connection requestBody: description: Mattermost configuration required: true content: application/json: schema: $ref: '#/components/schemas/Config' responses: "200": description: S3 Test successful content: application/json: schema: $ref: '#/components/schemas/StatusOK' "403": $ref: '#/components/responses/Forbidden' "500": $ref: '#/components/responses/InternalServerError' /api/v4/config: get: tags: - system summary: Get configuration description: | Retrieve the current server configuration ##### Permissions Must have `manage_system` permission. operationId: GetConfig responses: "200": description: Configuration retrieval successful content: application/json: schema: $ref: '#/components/schemas/Config' "400": $ref: '#/components/responses/BadRequest' "403": $ref: '#/components/responses/Forbidden' put: tags: - system summary: Update configuration description: > Submit a new configuration for the server to use. As of server version 4.8, the `PluginSettings.EnableUploads` setting cannot be modified by this endpoint. Note that the parameters that aren't set in the configuration that you provide will be reset to default values. Therefore, if you want to change a configuration parameter and leave the other ones unchanged, you need to get the existing configuration first, change the field that you want, then put that new configuration. ##### Permissions Must have `manage_system` permission. operationId: UpdateConfig requestBody: description: Mattermost configuration required: true content: application/json: schema: $ref: '#/components/schemas/Config' responses: "200": description: Configuration update successful content: application/json: schema: $ref: '#/components/schemas/Config' "400": $ref: '#/components/responses/BadRequest' "403": $ref: '#/components/responses/Forbidden' /api/v4/config/reload: post: tags: - system summary: Reload configuration description: | Reload the configuration file to pick up on any changes made to it. ##### Permissions Must have `manage_system` permission. operationId: ReloadConfig responses: "200": description: Configuration reload successful content: application/json: schema: $ref: '#/components/schemas/StatusOK' "400": $ref: '#/components/responses/BadRequest' "403": $ref: '#/components/responses/Forbidden' /api/v4/config/client: get: tags: - system summary: Get client configuration description: | Get a subset of the server configuration needed by the client. ##### Permissions No permission required. operationId: GetClientConfig parameters: - name: format in: query required: true description: Must be `old`, other formats not implemented yet schema: type: string responses: "200": description: Configuration retrieval successful "400": $ref: '#/components/responses/BadRequest' "501": $ref: '#/components/responses/NotImplemented' /api/v4/config/environment: get: tags: - system summary: Get configuration made through environment variables description: > Retrieve a json object mirroring the server configuration where fields are set to true if the corresponding config setting is set through an environment variable. Settings that haven't been set through environment variables will be missing from the object. __Minimum server version__: 4.10 ##### Permissions Must have `manage_system` permission. operationId: GetEnvironmentConfig responses: "200": description: Configuration retrieval successful content: application/json: schema: $ref: '#/components/schemas/EnvironmentConfig' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' /api/v4/config/patch: put: tags: - system summary: Patch configuration description: > Submit configuration to patch. As of server version 4.8, the `PluginSettings.EnableUploads` setting cannot be modified by this endpoint. ##### Permissions Must have `manage_system` permission. __Minimum server version__: 5.20 ##### Note The Plugins are stored as a map, and since a map may recursively go down to any depth, individual fields of a map are not changed. Consider using the `update config` (PUT api/v4/config) endpoint to update a plugins configurations. operationId: PatchConfig requestBody: description: Mattermost configuration required: true content: application/json: schema: $ref: '#/components/schemas/Config' responses: "200": description: Configuration update successful content: application/json: schema: $ref: '#/components/schemas/Config' "400": $ref: '#/components/responses/BadRequest' "403": $ref: '#/components/responses/Forbidden' /api/v4/license: post: tags: - system summary: Upload license file description: | Upload a license to enable enterprise features. __Minimum server version__: 4.0 ##### Permissions Must have `manage_system` permission. operationId: UploadLicenseFile requestBody: content: multipart/form-data: schema: type: object properties: license: description: The license to be uploaded type: string format: binary required: - license responses: "201": description: License file upload successful content: application/json: schema: $ref: '#/components/schemas/StatusOK' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "413": $ref: '#/components/responses/TooLarge' delete: tags: - system summary: Remove license file description: > Remove the license file from the server. This will disable all enterprise features. __Minimum server version__: 4.0 ##### Permissions Must have `manage_system` permission. operationId: RemoveLicenseFile responses: "200": description: License removal successful "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' /api/v4/license/client: get: tags: - system summary: Get client license description: > Get a subset of the server license needed by the client. ##### Permissions No permission required but having the `manage_system` permission returns more information. operationId: GetClientLicense parameters: - name: format in: query required: true description: Must be `old`, other formats not implemented yet schema: type: string responses: "200": description: License retrieval successful "400": $ref: '#/components/responses/BadRequest' "501": $ref: '#/components/responses/NotImplemented' /api/v4/license/renewal: get: tags: - system summary: Request the license renewal link description: > Request the renewal link that would be used to start the license renewal process __Minimum server version__: 5.32 ##### Permissions Must have `sysconsole_write_about` permission. operationId: RequestLicenseRenewalLink responses: "200": description: License renewal link obtained content: application/json: schema: $ref: '#/components/schemas/LicenseRenewalLink' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "500": $ref: '#/components/responses/InternalServerError' /api/v4/trial-license: post: tags: - system summary: Request and install a trial license for your server description: > Request and install a trial license for your server __Minimum server version__: 5.25 ##### Permissions Must have `manage_system` permission. operationId: RequestTrialLicense requestBody: description: License request required: true content: application/json: schema: type: object required: - users properties: users: type: integer description: Number of users requested (20% extra is going to be added) responses: "200": description: Trial license obtained and installed "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' /api/v4/trial-license/prev: get: tags: - system summary: Get last trial license used operationId: GetPrevTrialLicense description: > Get the last trial license used on the sevrer __Minimum server version__: 5.36 ##### Permissions Must have `manage_systems` permissions. responses: "200": description: License fetched successfully. "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' /api/v4/audits: get: tags: - system summary: Get audits description: > Get a page of audits for all users on the system, selected with `page` and `per_page` query parameters. ##### Permissions Must have `manage_system` permission. operationId: GetAudits parameters: - name: page in: query description: The page to select. schema: type: integer default: 0 - name: per_page in: query description: The number of audits per page. schema: type: integer default: 60 responses: "200": description: Audits retrieval successful content: application/json: schema: type: array items: $ref: '#/components/schemas/Audit' "403": $ref: '#/components/responses/Forbidden' /api/v4/caches/invalidate: post: tags: - system summary: Invalidate all the caches description: > Purge all the in-memory caches for the Mattermost server. This can have a temporary negative effect on performance while the caches are re-populated. ##### Permissions Must have `manage_system` permission. operationId: InvalidateCaches responses: "200": description: Caches invalidate successful content: application/json: schema: $ref: '#/components/schemas/StatusOK' "403": $ref: '#/components/responses/Forbidden' /api/v4/logs: get: tags: - system summary: Get logs description: > Get a page of server logs, selected with `page` and `logs_per_page` query parameters. ##### Permissions Must have `manage_system` permission. operationId: GetLogs parameters: - name: page in: query description: The page to select. schema: type: integer default: 0 - name: logs_per_page in: query description: The number of logs per page. There is a maximum limit of 10000 logs per page. schema: type: string default: "10000" responses: "200": description: Logs retrieval successful content: application/json: schema: type: array items: type: string "403": $ref: '#/components/responses/Forbidden' post: tags: - system summary: Add log message description: > Add log messages to the server logs. ##### Permissions Users with `manage_system` permission can log ERROR or DEBUG messages. Logged in users can log ERROR or DEBUG messages when `ServiceSettings.EnableDeveloper` is `true` or just DEBUG messages when `false`. Non-logged in users can log ERROR or DEBUG messages when `ServiceSettings.EnableDeveloper` is `true` and cannot log when `false`. operationId: PostLog requestBody: content: application/json: schema: type: object required: - level - message properties: level: type: string description: The error level, ERROR or DEBUG message: type: string description: Message to send to the server logs required: true responses: "200": description: Logs sent successful content: application/json: schema: type: object items: type: string "403": $ref: '#/components/responses/Forbidden' /api/v4/analytics/old: get: tags: - system summary: Get analytics description: > Get some analytics data about the system. This endpoint uses the old format, the `/analytics` route is reserved for the new format when it gets implemented. The returned JSON changes based on the `name` query parameter but is always key/value pairs. __Minimum server version__: 4.0 ##### Permissions Must have `manage_system` permission. operationId: GetAnalyticsOld parameters: - name: name in: query description: Possible values are "standard", "bot_post_counts_day", "post_counts_day", "user_counts_with_posts_day" or "extra_counts" schema: type: string default: standard - name: team_id in: query description: The team ID to filter the data by schema: type: string responses: "200": description: Analytics retrieval successful "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' /api/v4/server_busy: post: tags: - system summary: Set the server busy (high load) flag description: > Marks the server as currently having high load which disables non-critical services such as search, statuses and typing notifications. __Minimum server version__: 5.20 ##### Permissions Must have `manage_system` permission. operationId: SetServerBusy parameters: - name: seconds in: query description: Number of seconds until server is automatically marked as not busy. schema: type: string default: "3600" responses: "200": description: Server busy flag set successfully content: application/json: schema: $ref: '#/components/schemas/StatusOK' "400": $ref: '#/components/responses/BadRequest' "403": $ref: '#/components/responses/Forbidden' get: tags: - system summary: Get server busy expiry time. description: > Gets the timestamp corresponding to when the server busy flag will be automatically cleared. __Minimum server version__: 5.20 ##### Permissions Must have `manage_system` permission. operationId: GetServerBusyExpires responses: "200": description: Server busy expires timestamp retrieved successfully content: application/json: schema: $ref: '#/components/schemas/Server_Busy' "403": $ref: '#/components/responses/Forbidden' delete: tags: - system summary: Clears the server busy (high load) flag description: > Marks the server as not having high load which re-enables non-critical services such as search, statuses and typing notifications. __Minimum server version__: 5.20 ##### Permissions Must have `manage_system` permission. operationId: ClearServerBusy responses: "200": description: Server busy flag cleared successfully content: application/json: schema: $ref: '#/components/schemas/StatusOK' "403": $ref: '#/components/responses/Forbidden' /api/v4/notifications/ack: post: tags: - root summary: Acknowledge receiving of a notification description: > __Minimum server version__: 3.10 ##### Permissions Must be logged in. operationId: AcknowledgeNotification responses: "200": description: Status of the system content: application/json: schema: $ref: '#/components/schemas/PushNotification' "404": $ref: '#/components/responses/NotFound' /api/v4/redirect_location: get: tags: - system summary: Get redirect location description: > __Minimum server version__: 3.10 ##### Permissions Must be logged in. operationId: GetRedirectLocation parameters: - name: url in: query required: true description: Url to check schema: type: string responses: "200": description: Got redirect location content: image/*: schema: type: object properties: location: type: string "404": $ref: '#/components/responses/NotFound' /api/v4/image: get: tags: - system summary: Get an image by url description: > Fetches an image via Mattermost image proxy. __Minimum server version__: 3.10 ##### Permissions Must be logged in. operationId: GetImageByUrl responses: "200": description: Image found content: image/*: schema: type: string format: binary "404": $ref: '#/components/responses/NotFound' /api/v4/upgrade_to_enterprise: post: tags: - system summary: Executes an inplace upgrade from Team Edition to Enterprise Edition description: > It downloads the Mattermost Enterprise Edition of your current version and replace your current version with it. After the upgrade you need to restart the Mattermost server. __Minimum server version__: 5.27 ##### Permissions Must have `manage_system` permission. operationId: UpgradeToEnterprise responses: "202": description: Upgrade started content: application/json: schema: $ref: '#/components/schemas/PushNotification' "403": $ref: '#/components/responses/Forbidden' "429": $ref: '#/components/responses/TooManyRequests' /api/v4/upgrade_to_enterprise/status: get: tags: - system summary: Get the current status for the inplace upgrade from Team Edition to Enterprise Edition description: > It returns the percentage of completion of the current upgrade or the error if there is any. __Minimum server version__: 5.27 ##### Permissions Must have `manage_system` permission. operationId: UpgradeToEnterpriseStatus responses: "200": description: Upgrade status content: application/json: schema: type: object properties: percentage: type: integer description: Current percentage of the upgrade error: type: string description: Error happened during the upgrade "403": $ref: '#/components/responses/Forbidden' /api/v4/restart: post: tags: - system summary: Restart the system after an upgrade from Team Edition to Enterprise Edition description: > It restarts the current running mattermost instance to execute the new Enterprise binary. __Minimum server version__: 5.27 ##### Permissions Must have `manage_system` permission. operationId: RestartServer responses: "200": description: Restart started content: application/json: schema: $ref: '#/components/schemas/StatusOK' "403": $ref: '#/components/responses/Forbidden' /api/v4/integrity: post: tags: - system summary: Perform a database integrity check description: | Performs a database integrity check. __Note__: This check may temporarily harm system performance. __Minimum server version__: 5.28.0 __Local mode only__: This endpoint is only available through [local mode](https://docs.mattermost.com/administration/mmctl-cli-tool.html#local-mode). operationId: CheckIntegrity responses: "200": description: Integrity check successful content: application/json: schema: type: array items: $ref: '#/components/schemas/IntegrityCheckResult' /api/v4/system/support_packet: get: tags: - system summary: Download a zip file which contains helpful and useful information for troubleshooting your mattermost instance. description: | Download a zip file which contains helpful and useful information for troubleshooting your mattermost instance. __Minimum server version: 5.32__ ##### Permissions Must have any of the system console read permissions. ##### License Requires either a E10 or E20 license. operationId: GenerateSupportPacket responses: "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' /api/v4/emoji: post: tags: - emoji summary: Create a custom emoji description: | Create a custom emoji for the team. ##### Permissions Must be authenticated. operationId: CreateEmoji requestBody: content: multipart/form-data: schema: type: object properties: image: description: A file to be uploaded type: string format: binary emoji: description: A JSON object containing a `name` field with the name of the emoji and a `creator_id` field with the id of the authenticated user. type: string required: - image - emoji responses: "201": description: Emoji creation successful content: application/json: schema: $ref: '#/components/schemas/Emoji' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "413": $ref: '#/components/responses/TooLarge' "501": $ref: '#/components/responses/NotImplemented' get: tags: - emoji summary: Get a list of custom emoji description: > Get a page of metadata for custom emoji on the system. Since server version 4.7, sort using the `sort` query parameter. ##### Permissions Must be authenticated. operationId: GetEmojiList parameters: - name: page in: query description: The page to select. schema: type: integer default: 0 - name: per_page in: query description: The number of emojis per page. schema: type: integer default: 60 - name: sort in: query description: Either blank for no sorting or "name" to sort by emoji names. Minimum server version for sorting is 4.7. schema: type: string default: "" responses: "200": description: Emoji list retrieval successful content: application/json: schema: $ref: '#/components/schemas/Emoji' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "501": $ref: '#/components/responses/NotImplemented' /api/v4/emoji/{emoji_id}: get: tags: - emoji summary: Get a custom emoji description: | Get some metadata for a custom emoji. ##### Permissions Must be authenticated. operationId: GetEmoji parameters: - name: emoji_id in: path description: Emoji GUID required: true schema: type: string responses: "200": description: Emoji retrieval successful content: application/json: schema: $ref: '#/components/schemas/Emoji' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "404": $ref: '#/components/responses/NotFound' "501": $ref: '#/components/responses/NotImplemented' delete: tags: - emoji summary: Delete a custom emoji description: > Delete a custom emoji. ##### Permissions Must have the `manage_team` or `manage_system` permissions or be the user who created the emoji. operationId: DeleteEmoji parameters: - name: emoji_id in: path description: Emoji GUID required: true schema: type: string responses: "200": description: Emoji delete successful content: application/json: schema: $ref: '#/components/schemas/Emoji' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "501": $ref: '#/components/responses/NotImplemented' /api/v4/emoji/name/{emoji_name}: get: tags: - emoji summary: Get a custom emoji by name description: | Get some metadata for a custom emoji using its name. ##### Permissions Must be authenticated. __Minimum server version__: 4.7 operationId: GetEmojiByName parameters: - name: emoji_name in: path description: Emoji name required: true schema: type: string responses: "200": description: Emoji retrieval successful content: application/json: schema: $ref: '#/components/schemas/Emoji' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "404": $ref: '#/components/responses/NotFound' "501": $ref: '#/components/responses/NotImplemented' /api/v4/emoji/{emoji_id}/image: get: tags: - emoji summary: Get custom emoji image description: | Get the image for a custom emoji. ##### Permissions Must be authenticated. operationId: GetEmojiImage parameters: - name: emoji_id in: path description: Emoji GUID required: true schema: type: string responses: "200": description: Emoji image retrieval successful "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' "501": $ref: '#/components/responses/NotImplemented' /api/v4/emoji/search: post: tags: - emoji summary: Search custom emoji description: > Search for custom emoji by name based on search criteria provided in the request body. A maximum of 200 results are returned. ##### Permissions Must be authenticated. __Minimum server version__: 4.7 operationId: SearchEmoji requestBody: content: application/json: schema: type: object required: - term properties: term: description: The term to match against the emoji name. type: string prefix_only: description: Set to only search for names starting with the search term. type: string description: Search criteria required: true responses: "200": description: Emoji list retrieval successful content: application/json: schema: type: array items: $ref: '#/components/schemas/Emoji' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "501": $ref: '#/components/responses/NotImplemented' /api/v4/emoji/autocomplete: get: tags: - emoji summary: Autocomplete custom emoji description: > Get a list of custom emoji with names starting with or matching the provided name. Returns a maximum of 100 results. ##### Permissions Must be authenticated. __Minimum server version__: 4.7 operationId: AutocompleteEmoji parameters: - name: name in: query description: The emoji name to search. required: true schema: type: string responses: "200": description: Emoji list retrieval successful content: application/json: schema: $ref: '#/components/schemas/Emoji' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "501": $ref: '#/components/responses/NotImplemented' /api/v4/emoji/names: post: tags: - emoji summary: Get custom emojis by name description: > Get a list of custom emoji based on a provided list of emoji names. A maximum of 200 results are returned. ##### Permissions Must be authenticated. __Minimum server version__: 9.2 operationId: GetEmojisByNames requestBody: content: application/json: schema: type: array items: type: string description: List of emoji names required: true responses: "200": description: Emoji list retrieval successful content: application/json: schema: type: array items: $ref: '#/components/schemas/User' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "501": $ref: '#/components/responses/NotImplemented' /api/v4/hooks/incoming: post: tags: - webhooks summary: Create an incoming webhook description: | Create an incoming webhook for a channel. ##### Permissions `manage_webhooks` for the team the webhook is in. `manage_others_incoming_webhooks` for the team the webhook is in if the user is different than the requester. operationId: CreateIncomingWebhook requestBody: content: application/json: schema: type: object required: - channel_id properties: channel_id: type: string description: The ID of a public channel or private group that receives the webhook payloads. user_id: type: string description: The ID of the owner of the webhook if different than the requester. Required for [local mode](https://docs.mattermost.com/administration/mmctl-cli-tool.html#local-mode). display_name: type: string description: The display name for this incoming webhook description: type: string description: The description for this incoming webhook username: type: string description: The username this incoming webhook will post as. icon_url: type: string description: The profile picture this incoming webhook will use when posting. description: Incoming webhook to be created required: true responses: "201": description: Incoming webhook creation successful content: application/json: schema: $ref: '#/components/schemas/IncomingWebhook' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' get: tags: - webhooks summary: List incoming webhooks description: > Get a page of a list of incoming webhooks. Optionally filter for a specific team using query parameters. ##### Permissions `manage_webhooks` for the system or `manage_webhooks` for the specific team. operationId: GetIncomingWebhooks parameters: - name: page in: query description: The page to select. schema: type: integer default: 0 - name: per_page in: query description: The number of hooks per page. schema: type: integer default: 60 - name: team_id in: query description: The ID of the team to get hooks for. schema: type: string responses: "200": description: Incoming webhooks retrieval successful content: application/json: schema: type: array items: $ref: '#/components/schemas/IncomingWebhook' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' /api/v4/hooks/incoming/{hook_id}: get: tags: - webhooks summary: Get an incoming webhook description: > Get an incoming webhook given the hook id. ##### Permissions `manage_webhooks` for system or `manage_webhooks` for the specific team or `manage_webhooks` for the channel. operationId: GetIncomingWebhook parameters: - name: hook_id in: path description: Incoming Webhook GUID required: true schema: type: string responses: "200": description: Webhook retrieval successful content: application/json: schema: $ref: '#/components/schemas/IncomingWebhook' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' delete: tags: - webhooks summary: Delete an incoming webhook description: > Delete an incoming webhook given the hook id. ##### Permissions `manage_webhooks` for system or `manage_webhooks` for the specific team or `manage_webhooks` for the channel. operationId: DeleteIncomingWebhook parameters: - name: hook_id in: path description: Incoming webhook GUID required: true schema: type: string responses: "200": description: Webhook 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' "404": $ref: '#/components/responses/NotFound' put: tags: - webhooks summary: Update an incoming webhook description: > Update an incoming webhook given the hook id. ##### Permissions `manage_webhooks` for system or `manage_webhooks` for the specific team or `manage_webhooks` for the channel. operationId: UpdateIncomingWebhook parameters: - name: hook_id in: path description: Incoming Webhook GUID required: true schema: type: string requestBody: content: application/json: schema: type: object required: - id - channel_id - display_name - description properties: id: type: string description: Incoming webhook GUID channel_id: type: string description: The ID of a public channel or private group that receives the webhook payloads. display_name: type: string description: The display name for this incoming webhook description: type: string description: The description for this incoming webhook username: type: string description: The username this incoming webhook will post as. icon_url: type: string description: The profile picture this incoming webhook will use when posting. description: Incoming webhook to be updated required: true responses: "200": description: Webhook update successful content: application/json: schema: $ref: '#/components/schemas/IncomingWebhook' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' /api/v4/hooks/outgoing: post: tags: - webhooks summary: Create an outgoing webhook description: | Create an outgoing webhook for a team. ##### Permissions `manage_webhooks` for the team the webhook is in. `manage_others_outgoing_webhooks` for the team the webhook is in if the user is different than the requester. operationId: CreateOutgoingWebhook requestBody: content: application/json: schema: type: object required: - team_id - display_name - trigger_words - callback_urls properties: team_id: description: The ID of the team that the webhook watchs type: string channel_id: description: The ID of a public channel that the webhook watchs type: string creator_id: description: The ID of the owner of the webhook if different than the requester. Required in [local mode](https://docs.mattermost.com/administration/mmctl-cli-tool.html#local-mode). type: string description: description: The description for this outgoing webhook type: string display_name: description: The display name for this outgoing webhook type: string trigger_words: description: List of words for the webhook to trigger on type: array items: type: string trigger_when: description: When to trigger the webhook, `0` when a trigger word is present at all and `1` if the message starts with a trigger word type: integer callback_urls: description: The URLs to POST the payloads to when the webhook is triggered type: array items: type: string content_type: description: The format to POST the data in, either `application/json` or `application/x-www-form-urlencoded` default: application/x-www-form-urlencoded type: string description: Outgoing webhook to be created required: true responses: "201": description: Outgoing webhook creation successful content: application/json: schema: $ref: '#/components/schemas/OutgoingWebhook' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' get: tags: - webhooks summary: List outgoing webhooks description: > Get a page of a list of outgoing webhooks. Optionally filter for a specific team or channel using query parameters. ##### Permissions `manage_webhooks` for the system or `manage_webhooks` for the specific team/channel. operationId: GetOutgoingWebhooks parameters: - name: page in: query description: The page to select. schema: type: integer default: 0 - name: per_page in: query description: The number of hooks per page. schema: type: integer default: 60 - name: team_id in: query description: The ID of the team to get hooks for. schema: type: string - name: channel_id in: query description: The ID of the channel to get hooks for. schema: type: string responses: "200": description: Outgoing webhooks retrieval successful content: application/json: schema: type: array items: $ref: '#/components/schemas/OutgoingWebhook' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' /api/v4/hooks/outgoing/{hook_id}: get: tags: - webhooks summary: Get an outgoing webhook description: > Get an outgoing webhook given the hook id. ##### Permissions `manage_webhooks` for system or `manage_webhooks` for the specific team or `manage_webhooks` for the channel. operationId: GetOutgoingWebhook parameters: - name: hook_id in: path description: Outgoing webhook GUID required: true schema: type: string responses: "200": description: Outgoing webhook retrieval successful content: application/json: schema: $ref: '#/components/schemas/OutgoingWebhook' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' delete: tags: - webhooks summary: Delete an outgoing webhook description: > Delete an outgoing webhook given the hook id. ##### Permissions `manage_webhooks` for system or `manage_webhooks` for the specific team or `manage_webhooks` for the channel. operationId: DeleteOutgoingWebhook parameters: - name: hook_id in: path description: Outgoing webhook GUID required: true schema: type: string responses: "200": description: Webhook 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' "404": $ref: '#/components/responses/NotFound' put: tags: - webhooks summary: Update an outgoing webhook description: > Update an outgoing webhook given the hook id. ##### Permissions `manage_webhooks` for system or `manage_webhooks` for the specific team or `manage_webhooks` for the channel. operationId: UpdateOutgoingWebhook parameters: - name: hook_id in: path description: outgoing Webhook GUID required: true schema: type: string requestBody: content: application/json: schema: type: object required: - id - channel_id - display_name - description properties: id: type: string description: Outgoing webhook GUID channel_id: type: string description: The ID of a public channel or private group that receives the webhook payloads. display_name: type: string description: The display name for this incoming webhook description: type: string description: The description for this incoming webhook description: Outgoing webhook to be updated required: true responses: "200": description: Webhook update successful content: application/json: schema: $ref: '#/components/schemas/OutgoingWebhook' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' /api/v4/hooks/outgoing/{hook_id}/regen_token: post: tags: - webhooks summary: Regenerate the token for the outgoing webhook. description: > Regenerate the token for the outgoing webhook. ##### Permissions `manage_webhooks` for system or `manage_webhooks` for the specific team or `manage_webhooks` for the channel. operationId: RegenOutgoingHookToken parameters: - name: hook_id in: path description: Outgoing webhook GUID required: true schema: type: string responses: "200": description: Webhook token regenerate 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/saml/metadata: get: tags: - SAML summary: Get metadata description: | Get SAML metadata from the server. SAML must be configured properly. ##### Permissions No permission required. operationId: GetSamlMetadata responses: "200": description: SAML metadata retrieval successful content: application/json: schema: type: string "501": $ref: '#/components/responses/NotImplemented' /api/v4/saml/metadatafromidp: post: tags: - SAML summary: Get metadata from Identity Provider description: | Get SAML metadata from the Identity Provider. SAML must be configured properly. ##### Permissions No permission required. operationId: GetSamlMetadataFromIdp requestBody: content: application/json: schema: type: object properties: saml_metadata_url: type: string description: The URL from which to retrieve the SAML IDP data. responses: "200": description: SAML metadata retrieval successful content: application/json: schema: type: string "501": $ref: '#/components/responses/NotImplemented' /api/v4/saml/certificate/idp: post: tags: - SAML summary: Upload IDP certificate description: > Upload the IDP certificate to be used with your SAML configuration. The server will pick a hard-coded filename for the IdpCertificateFile setting in your `config.json`. ##### Permissions Must have `sysconsole_write_authentication` permission. operationId: UploadSamlIdpCertificate requestBody: content: multipart/form-data: schema: type: object properties: certificate: description: The IDP certificate file type: string format: binary required: - certificate responses: "200": description: SAML certificate upload 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' delete: tags: - SAML summary: Remove IDP certificate description: > Delete the current IDP certificate being used with your SAML configuration. This will also disable SAML on your system as this certificate is required for SAML. ##### Permissions Must have `sysconsole_write_authentication` permission. operationId: DeleteSamlIdpCertificate responses: "200": description: SAML certificate delete successful content: application/json: schema: $ref: '#/components/schemas/StatusOK' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "501": $ref: '#/components/responses/NotImplemented' /api/v4/saml/certificate/public: post: tags: - SAML summary: Upload public certificate description: > Upload the public certificate to be used for encryption with your SAML configuration. The server will pick a hard-coded filename for the PublicCertificateFile setting in your `config.json`. ##### Permissions Must have `sysconsole_write_authentication` permission. operationId: UploadSamlPublicCertificate requestBody: content: multipart/form-data: schema: type: object properties: certificate: description: The public certificate file type: string format: binary required: - certificate responses: "200": description: SAML certificate upload 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' delete: tags: - SAML summary: Remove public certificate description: > Delete the current public certificate being used with your SAML configuration. This will also disable encryption for SAML on your system as this certificate is required for that. ##### Permissions Must have `sysconsole_write_authentication` permission. operationId: DeleteSamlPublicCertificate responses: "200": description: SAML certificate delete successful content: application/json: schema: $ref: '#/components/schemas/StatusOK' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "501": $ref: '#/components/responses/NotImplemented' /api/v4/saml/certificate/private: post: tags: - SAML summary: Upload private key description: > Upload the private key to be used for encryption with your SAML configuration. The server will pick a hard-coded filename for the PrivateKeyFile setting in your `config.json`. ##### Permissions Must have `sysconsole_write_authentication` permission. operationId: UploadSamlPrivateCertificate requestBody: content: multipart/form-data: schema: type: object properties: certificate: description: The private key file type: string format: binary required: - certificate responses: "200": description: SAML certificate upload 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' delete: tags: - SAML summary: Remove private key description: > Delete the current private key being used with your SAML configuration. This will also disable encryption for SAML on your system as this key is required for that. ##### Permissions Must have `sysconsole_write_authentication` permission. operationId: DeleteSamlPrivateCertificate responses: "200": description: SAML certificate delete successful content: application/json: schema: $ref: '#/components/schemas/StatusOK' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "501": $ref: '#/components/responses/NotImplemented' /api/v4/saml/certificate/status: get: tags: - SAML summary: Get certificate status description: > Get the status of the uploaded certificates and keys in use by your SAML configuration. ##### Permissions Must have `sysconsole_write_authentication` permission. operationId: GetSamlCertificateStatus responses: "200": description: SAML certificate status retrieval successful content: application/json: schema: $ref: '#/components/schemas/SamlCertificateStatus' "403": $ref: '#/components/responses/Forbidden' "501": $ref: '#/components/responses/NotImplemented' /api/v4/saml/reset_auth_data: post: tags: - SAML summary: Reset AuthData to Email description: > Reset the AuthData field of SAML users to their email. This is meant to be used when the "id" attribute is set to an empty value ("") from a previously non-empty value. __Minimum server version__: 5.35 ##### Permissions Must have `manage_system` permission. operationId: ResetSamlAuthDataToEmail requestBody: content: application/json: schema: type: object properties: include_deleted: type: boolean default: false description: Whether to include deleted users. dry_run: type: boolean default: false description: If set to true, the number of users who would be affected is returned. user_ids: type: array items: type: string default: [] description: If set to a non-empty array, then users whose IDs are not in the array will be excluded. responses: "200": description: AuthData successfully reset content: application/json: schema: type: object properties: num_affected: type: integer description: The number of users whose AuthData field was reset. "403": $ref: '#/components/responses/Forbidden' "501": $ref: '#/components/responses/NotImplemented' /api/v4/compliance/reports: post: tags: - compliance summary: Create report description: | Create and save a compliance report. ##### Permissions Must have `manage_system` permission. operationId: CreateComplianceReport responses: "201": description: Compliance report creation successful content: application/json: schema: $ref: '#/components/schemas/Compliance' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "501": $ref: '#/components/responses/NotImplemented' get: tags: - compliance summary: Get reports description: > Get a list of compliance reports previously created by page, selected with `page` and `per_page` query parameters. ##### Permissions Must have `manage_system` permission. operationId: GetComplianceReports parameters: - name: page in: query description: The page to select. schema: type: integer default: 0 - name: per_page in: query description: The number of reports per page. schema: type: integer default: 60 responses: "200": description: Compliance reports retrieval successful content: application/json: schema: type: array items: $ref: '#/components/schemas/Compliance' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "501": $ref: '#/components/responses/NotImplemented' /api/v4/compliance/reports/{report_id}: get: tags: - compliance summary: Get a report description: | Get a compliance reports previously created. ##### Permissions Must have `manage_system` permission. operationId: GetComplianceReport parameters: - name: report_id in: path description: Compliance report GUID required: true schema: type: string responses: "200": description: Compliance report retrieval successful content: application/json: schema: $ref: '#/components/schemas/Compliance' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "501": $ref: '#/components/responses/NotImplemented' /api/v4/compliance/reports/{report_id}/download: get: tags: - compliance summary: Download a report description: | Download the full contents of a report as a file. ##### Permissions Must have `manage_system` permission. operationId: DownloadComplianceReport parameters: - name: report_id in: path description: Compliance report GUID required: true schema: type: string responses: "200": description: The compliance report file "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "501": $ref: '#/components/responses/NotImplemented' /api/v4/ldap/sync: post: tags: - LDAP summary: Sync with LDAP description: > Synchronize any user attribute changes in the configured AD/LDAP server with Mattermost. ##### Permissions Must have `manage_system` permission. operationId: SyncLdap responses: "200": description: LDAP sync successful content: application/json: schema: $ref: '#/components/schemas/StatusOK' "501": $ref: '#/components/responses/NotImplemented' /api/v4/ldap/test: post: tags: - LDAP summary: Test LDAP configuration description: > Test the current AD/LDAP configuration to see if the AD/LDAP server can be contacted successfully. ##### Permissions Must have `manage_system` permission. operationId: TestLdap responses: "200": description: LDAP test successful content: application/json: schema: $ref: '#/components/schemas/StatusOK' "500": $ref: '#/components/responses/InternalServerError' "501": $ref: '#/components/responses/NotImplemented' /api/v4/ldap/groups: get: tags: - ldap summary: Returns a list of LDAP groups description: > ##### Permissions Must have `manage_system` permission. __Minimum server version__: 5.11 operationId: GetLdapGroups parameters: - name: q in: query description: Search term 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 users per page. There is a maximum limit of 200 users per page. schema: type: integer default: 60 responses: "200": description: LDAP group page retrieval successful content: application/json: schema: type: array items: $ref: '#/components/schemas/LDAPGroupsPaged' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' /api/v4/ldap/groups/{remote_id}/link: post: tags: - ldap summary: Link a LDAP group description: > ##### Permissions Must have `manage_system` permission. __Minimum server version__: 5.11 operationId: LinkLdapGroup parameters: - name: remote_id in: path description: Group GUID required: true schema: type: string responses: "201": description: LDAP group successfully linked content: application/json: schema: $ref: '#/components/schemas/StatusOK' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' delete: tags: - groups summary: Delete a link for LDAP group description: > ##### Permissions Must have `manage_system` permission. __Minimum server version__: 5.11 operationId: UnlinkLdapGroup parameters: - name: remote_id in: path description: Group GUID required: true schema: type: string responses: "200": description: Successfully deleted ldap group link 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/ldap/migrateid: post: tags: - LDAP summary: Migrate Id LDAP description: > Migrate LDAP IdAttribute to new value. ##### Permissions Must have `manage_system` permission. __Minimum server version__: 5.26 operationId: MigrateIdLdap requestBody: content: application/json: schema: type: object required: - toAttribute properties: toAttribute: description: New IdAttribute value type: string required: true responses: "200": description: Migration successful content: application/json: schema: $ref: '#/components/schemas/StatusOK' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "500": $ref: '#/components/responses/InternalServerError' "501": $ref: '#/components/responses/NotImplemented' /api/v4/ldap/certificate/public: post: tags: - LDAP summary: Upload public certificate description: > Upload the public certificate to be used for TLS verification. The server will pick a hard-coded filename for the PublicCertificateFile setting in your `config.json`. ##### Permissions Must have `manage_system` permission. operationId: UploadLdapPublicCertificate requestBody: content: multipart/form-data: schema: type: object properties: certificate: description: The public certificate file type: string format: binary required: - certificate responses: "200": description: LDAP certificate upload 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' delete: tags: - LDAP summary: Remove public certificate description: > Delete the current public certificate being used for TLS verification. ##### Permissions Must have `manage_system` permission. operationId: DeleteLdapPublicCertificate responses: "200": description: LDAP certificate delete successful content: application/json: schema: $ref: '#/components/schemas/StatusOK' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "501": $ref: '#/components/responses/NotImplemented' /api/v4/ldap/certificate/private: post: tags: - LDAP summary: Upload private key description: > Upload the private key to be used for TLS verification. The server will pick a hard-coded filename for the PrivateKeyFile setting in your `config.json`. ##### Permissions Must have `manage_system` permission. operationId: UploadLdapPrivateCertificate requestBody: content: multipart/form-data: schema: type: object properties: certificate: description: The private key file type: string format: binary required: - certificate responses: "200": description: LDAP certificate upload 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' delete: tags: - LDAP summary: Remove private key description: > Delete the current private key being used with your TLS verification. ##### Permissions Must have `manage_system` permission. operationId: DeleteLdapPrivateCertificate responses: "200": description: LDAP certificate delete successful content: application/json: schema: $ref: '#/components/schemas/StatusOK' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "501": $ref: '#/components/responses/NotImplemented' /api/v4/ldap/users/{user_id}/group_sync_memberships: post: tags: - LDAP summary: Create memberships for LDAP configured channels and teams for this user description: > Add the user to each channel and team configured for each LDAP group of whicht the user is a member. ##### Permissions Must have `sysconsole_write_user_management_groups` permission. operationId: AddUserToGroupSyncables parameters: - name: user_id in: path description: User Id required: true schema: type: string responses: "200": description: Channel and team memberships created as needed. 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/groups: get: tags: - groups summary: Get groups description: > Retrieve a list of all groups not associated to a particular channel or team. `not_associated_to_team` **OR** `not_associated_to_channel` is required. If you use `not_associated_to_team`, you must be a team admin for that particular team (permission to manage that team). If you use `not_associated_to_channel`, you must be a channel admin for that particular channel (permission to manage that channel). __Minimum server version__: 5.11 operationId: GetGroups parameters: - name: page in: query description: The page to select. schema: type: integer default: 0 - name: per_page in: query description: The number of groups per page. schema: type: integer default: 60 - name: q in: query description: String to pattern match the `name` and `display_name` field. Will return all groups whose `name` and `display_name` field match any of the text. schema: type: string - name: include_member_count in: query description: Boolean which adds the `member_count` attribute to each group JSON object schema: type: boolean - name: not_associated_to_team in: query description: Team GUID which is used to return all the groups not associated to this team required: true schema: type: string - name: not_associated_to_channel in: query description: Group GUID which is used to return all the groups not associated to this channel required: true schema: type: string - name: since in: query description: > Only return groups that have been modified since the given Unix timestamp (in milliseconds). All modified groups, including deleted and created groups, will be returned. __Minimum server version__: 5.24 schema: type: integer - name: filter_allow_reference in: query description: Boolean which filters the group entries with the `allow_reference` attribute set. schema: type: boolean default: false responses: "200": description: Group list retrieval successful content: application/json: schema: type: array items: $ref: '#/components/schemas/Group' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "501": $ref: '#/components/responses/NotImplemented' post: tags: - groups summary: Create a custom group description: | Create a `custom` type group. #### Permission Must have `create_custom_group` permission. __Minimum server version__: 6.3 operationId: CreateGroup requestBody: content: application/json: schema: type: object required: - group - user_ids properties: group: type: object required: - name - display_name - source - allow_reference description: Group object to create. properties: name: type: string description: The unique group name used for at-mentioning. display_name: type: string description: The display name of the group which can include spaces. source: type: string description: Must be `custom` allow_reference: type: boolean description: Must be true user_ids: type: array description: The user ids of the group members to add. items: type: string description: Group object and initial members. required: true responses: "501": description: | Group has an invalid `source`, or `allow_reference` is not `true`, or group has a `remote_id`. "400": $ref: '#/components/responses/BadRequest' "201": description: Group creation and memberships successful. "403": $ref: '#/components/responses/Forbidden' /api/v4/groups/{group_id}: get: tags: - groups summary: Get a group description: | Get group from the provided group id string ##### Permissions Must have `manage_system` permission. __Minimum server version__: 5.11 operationId: GetGroup parameters: - name: group_id in: path description: Group GUID required: true schema: type: string responses: "200": description: Group retrieval successful content: application/json: schema: $ref: '#/components/schemas/Group' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "501": $ref: '#/components/responses/NotImplemented' delete: tags: - groups summary: Deletes a custom group description: | Soft deletes a custom group. ##### Permissions Must have `custom_group_delete` permission for the given group. __Minimum server version__: 6.3 operationId: DeleteGroup parameters: - name: group_id in: path description: The ID of the group. required: true schema: type: string responses: "403": $ref: '#/components/responses/Forbidden' "501": description: The group doesn't have a `source` value of `custom`. "404": description: Group is already deleted or doesn't exist. "200": description: Successfully deleted the group. content: application/json: schema: $ref: '#/components/schemas/StatusOK' /api/v4/groups/{group_id}/patch: put: tags: - groups summary: Patch a group description: > Partially update a group by providing only the fields you want to update. Omitted fields will not be updated. The fields that can be updated are defined in the request body, all other provided fields will be ignored. ##### Permissions Must have `manage_system` permission. __Minimum server version__: 5.11 operationId: PatchGroup parameters: - name: group_id in: path description: Group GUID required: true schema: type: string requestBody: content: application/json: schema: type: object properties: name: type: string display_name: type: string description: type: string description: Group object that is to be updated required: true responses: "200": description: Group patch successful content: application/json: schema: $ref: '#/components/schemas/Group' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "501": $ref: '#/components/responses/NotImplemented' /api/v4/groups/{group_id}/restore: post: tags: - groups summary: Restore a previously deleted group. description: > Restores a previously deleted custom group, allowing it to be used normally. May not be used with LDAP groups. ##### Permissions Must have `restore_custom_group` permission for the given group. __Minimum server version__: 7.7 operationId: RestoreGroup parameters: - name: group_id in: path description: Group GUID required: true schema: type: string responses: "200": description: Group restored successfully 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/groups/{group_id}/teams/{team_id}/link: post: tags: - groups summary: Link a team to a group description: | Link a team to a group ##### Permissions Must have `manage_team` permission. __Minimum server version__: 5.11 operationId: LinkGroupSyncableForTeam parameters: - name: group_id in: path description: Group GUID required: true schema: type: string - name: team_id in: path description: Team GUID required: true schema: type: string responses: "201": description: Team successfully linked to group content: application/json: schema: $ref: '#/components/schemas/GroupSyncableTeam' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "501": $ref: '#/components/responses/NotImplemented' delete: tags: - groups summary: Delete a link from a team to a group description: | Delete a link from a team to a group ##### Permissions Must have `manage_team` permission. __Minimum server version__: 5.11 operationId: UnlinkGroupSyncableForTeam parameters: - name: group_id in: path description: Group GUID required: true schema: type: string - name: team_id in: path description: Team GUID required: true schema: type: string responses: "200": description: Successfully deleted link between team and group 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/groups/{group_id}/channels/{channel_id}/link: post: tags: - groups summary: Link a channel to a group description: > Link a channel to a group ##### Permissions If the channel is private, you must have `manage_private_channel_members` permission. Otherwise, you must have the `manage_public_channel_members` permission. __Minimum server version__: 5.11 operationId: LinkGroupSyncableForChannel parameters: - name: group_id in: path description: Group GUID required: true schema: type: string - name: channel_id in: path description: Channel GUID required: true schema: type: string responses: "201": description: Channel successfully linked to group content: application/json: schema: $ref: '#/components/schemas/GroupSyncableChannel' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "501": $ref: '#/components/responses/NotImplemented' delete: tags: - groups summary: Delete a link from a channel to a group description: > Delete a link from a channel to a group ##### Permissions If the channel is private, you must have `manage_private_channel_members` permission. Otherwise, you must have the `manage_public_channel_members` permission. __Minimum server version__: 5.11 operationId: UnlinkGroupSyncableForChannel parameters: - name: group_id in: path description: Group GUID required: true schema: type: string - name: channel_id in: path description: Channel GUID required: true schema: type: string responses: "200": description: Successfully deleted link between channel and group 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/groups/{group_id}/teams/{team_id}: get: tags: - groups summary: Get GroupSyncable from Team ID description: | Get the GroupSyncable object with group_id and team_id from params ##### Permissions Must have `manage_system` permission. __Minimum server version__: 5.11 operationId: GetGroupSyncableForTeamId parameters: - name: group_id in: path description: Group GUID required: true schema: type: string - name: team_id in: path description: Team GUID required: true schema: type: string responses: "200": description: GroupSyncable object retrieval successful content: application/json: schema: $ref: '#/components/schemas/GroupSyncableTeam' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "500": $ref: '#/components/responses/InternalServerError' "501": $ref: '#/components/responses/NotImplemented' /api/v4/groups/{group_id}/channels/{channel_id}: get: tags: - groups summary: Get GroupSyncable from channel ID description: | Get the GroupSyncable object with group_id and channel_id from params ##### Permissions Must have `manage_system` permission. __Minimum server version__: 5.11 operationId: GetGroupSyncableForChannelId parameters: - name: group_id in: path description: Group GUID required: true schema: type: string - name: channel_id in: path description: Channel GUID required: true schema: type: string responses: "200": description: GroupSyncable object retrieval successful content: application/json: schema: $ref: '#/components/schemas/GroupSyncableChannel' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "500": $ref: '#/components/responses/InternalServerError' "501": $ref: '#/components/responses/NotImplemented' /api/v4/groups/{group_id}/teams: get: tags: - groups summary: Get group teams description: | Retrieve the list of teams associated to the group ##### Permissions Must have `manage_system` permission. __Minimum server version__: 5.11 operationId: GetGroupSyncablesTeams parameters: - name: group_id in: path description: Group GUID required: true schema: type: string responses: "200": description: Teams list retrieval successful content: application/json: schema: type: array items: $ref: '#/components/schemas/GroupSyncableTeams' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "500": $ref: '#/components/responses/InternalServerError' "501": $ref: '#/components/responses/NotImplemented' /api/v4/groups/{group_id}/channels: get: tags: - groups summary: Get group channels description: | Retrieve the list of channels associated to the group ##### Permissions Must have `manage_system` permission. __Minimum server version__: 5.11 operationId: GetGroupSyncablesChannels parameters: - name: group_id in: path description: Group GUID required: true schema: type: string responses: "200": description: Channel list retrieval successful content: application/json: schema: type: array items: $ref: '#/components/schemas/GroupSyncableChannels' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "500": $ref: '#/components/responses/InternalServerError' "501": $ref: '#/components/responses/NotImplemented' /api/v4/groups/{group_id}/teams/{team_id}/patch: put: tags: - groups summary: Patch a GroupSyncable associated to Team description: > Partially update a GroupSyncable by providing only the fields you want to update. Omitted fields will not be updated. The fields that can be updated are defined in the request body, all other provided fields will be ignored. ##### Permissions Must have `manage_system` permission. __Minimum server version__: 5.11 operationId: PatchGroupSyncableForTeam parameters: - name: group_id in: path description: Group GUID required: true schema: type: string - name: team_id in: path description: Team GUID required: true schema: type: string requestBody: description: GroupSyncable object that is to be updated required: true content: application/json: schema: type: object properties: auto_add: type: boolean responses: "200": description: GroupSyncable patch successful content: application/json: schema: $ref: '#/components/schemas/GroupSyncableTeam' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "501": $ref: '#/components/responses/NotImplemented' /api/v4/groups/{group_id}/channels/{channel_id}/patch: put: tags: - groups summary: Patch a GroupSyncable associated to Channel description: > Partially update a GroupSyncable by providing only the fields you want to update. Omitted fields will not be updated. The fields that can be updated are defined in the request body, all other provided fields will be ignored. ##### Permissions Must have `manage_system` permission. __Minimum server version__: 5.11 operationId: PatchGroupSyncableForChannel parameters: - name: group_id in: path description: Group GUID required: true schema: type: string - name: channel_id in: path description: Channel GUID required: true schema: type: string requestBody: description: GroupSyncable object that is to be updated required: true content: application/json: schema: type: object properties: auto_add: type: boolean responses: "200": description: GroupSyncable patch successful content: application/json: schema: $ref: '#/components/schemas/GroupSyncableChannel' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "501": $ref: '#/components/responses/NotImplemented' /api/v4/groups/{group_id}/members: get: tags: - groups summary: Get group users description: | Retrieve the list of users associated with a given group. ##### Permissions Must have `manage_system` permission. __Minimum server version__: 5.11 operationId: GetGroupUsers parameters: - name: group_id in: path description: Group 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 groups per page. schema: type: integer default: 60 responses: "200": description: User list retrieval successful content: application/json: schema: type: object properties: members: type: array items: $ref: '#/components/schemas/User' total_member_count: type: integer "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "500": $ref: '#/components/responses/InternalServerError' "501": $ref: '#/components/responses/NotImplemented' delete: tags: - groups summary: Removes members from a custom group description: | Soft deletes a custom group members. ##### Permissions Must have `custom_group_manage_members` permission for the given group. __Minimum server version__: 6.3 operationId: DeleteGroupMembers parameters: - name: group_id in: path description: The ID of the group to delete. required: true schema: type: string requestBody: required: true content: application/json: schema: type: object description: An object containing the user ids of the members to remove. properties: user_ids: type: array items: type: string responses: "403": $ref: '#/components/responses/Forbidden' "501": description: If the group does not have a `source` value of `custom`. "404": description: Can't find the group. "200": description: Successfully deleted the group members. content: application/json: schema: $ref: '#/components/schemas/StatusOK' post: tags: - groups summary: Adds members to a custom group description: | Adds members to a custom group. ##### Permissions Must have `custom_group_manage_members` permission for the given group. __Minimum server version__: 6.3 operationId: AddGroupMembers parameters: - name: group_id in: path description: The ID of the group. required: true schema: type: string requestBody: required: true content: application/json: schema: type: object description: An object containing the user ids of the members to add. properties: user_ids: type: array items: type: string responses: "403": $ref: '#/components/responses/Forbidden' "501": description: If the group does not have a `source` value of `custom`. "404": description: Can't find the group. "200": description: Successfully added the group members. content: application/json: schema: $ref: '#/components/schemas/StatusOK' /api/v4/groups/{group_id}/stats: get: tags: - groups summary: Get group stats description: | Retrieve the stats of a given group. ##### Permissions Must have `manage_system` permission. __Minimum server version__: 5.26 operationId: GetGroupStats parameters: - name: group_id in: path description: Group GUID required: true schema: type: string responses: "200": description: Group stats retrieval successful content: application/json: schema: type: object properties: group_id: type: string total_member_count: type: integer "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "500": $ref: '#/components/responses/InternalServerError' "501": $ref: '#/components/responses/NotImplemented' /api/v4/channels/{channel_id}/groups: get: tags: - groups summary: Get channel groups description: | Retrieve the list of groups associated with a given channel. ##### Permissions Must have `manage_system` permission. __Minimum server version__: 5.11 operationId: GetGroupsByChannel 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 groups per page. schema: type: integer default: 60 - name: filter_allow_reference in: query description: Boolean which filters the group entries with the `allow_reference` attribute set. schema: type: boolean default: false responses: "200": description: Group list retrieval successful content: application/json: schema: type: array items: $ref: '#/components/schemas/Group' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "500": $ref: '#/components/responses/InternalServerError' "501": $ref: '#/components/responses/NotImplemented' /api/v4/teams/{team_id}/groups: get: tags: - groups summary: Get team groups description: | Retrieve the list of groups associated with a given team. ##### Permissions Must have the `list_team_channels` permission. __Minimum server version__: 5.11 operationId: GetGroupsByTeam 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 groups per page. schema: type: integer default: 60 - name: filter_allow_reference in: query description: Boolean which filters in the group entries with the `allow_reference` attribute set. schema: type: boolean default: false responses: "200": description: Group list retrieval successful content: application/json: schema: type: array items: $ref: '#/components/schemas/Group' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "500": $ref: '#/components/responses/InternalServerError' "501": $ref: '#/components/responses/NotImplemented' /api/v4/teams/{team_id}/groups_by_channels: get: tags: - groups summary: Get team groups by channels description: | Retrieve the set of groups associated with the channels in the given team grouped by channel. ##### Permissions Must have the `list_team_channels` permission. __Minimum server version__: 5.11 operationId: GetGroupsAssociatedToChannelsByTeam 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 groups per page. schema: type: integer default: 60 - name: filter_allow_reference in: query description: Boolean which filters in the group entries with the `allow_reference` attribute set. schema: type: boolean default: false - name: paginate in: query description: Boolean to determine whether the pagination should be applied or not schema: type: boolean default: false responses: "200": description: Group list retrieval successful content: application/json: schema: type: object items: $ref: '#/components/schemas/GroupsAssociatedToChannels' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "500": $ref: '#/components/responses/InternalServerError' "501": $ref: '#/components/responses/NotImplemented' /api/v4/users/{user_id}/groups: get: tags: - groups summary: Get groups for a userId description: | Retrieve the list of groups associated to the user __Minimum server version__: 5.24 operationId: GetGroupsByUserId parameters: - name: user_id in: path description: User GUID required: true schema: type: string responses: "200": description: Group list retrieval successful content: application/json: schema: type: array items: $ref: '#/components/schemas/Group' "400": $ref: '#/components/responses/BadRequest' "501": $ref: '#/components/responses/NotImplemented' /api/v4/cluster/status: get: tags: - cluster summary: Get cluster status description: > Get a set of information for each node in the cluster, useful for checking the status and health of each node. ##### Permissions Must have `manage_system` permission. operationId: GetClusterStatus responses: "200": description: Cluster status retrieval successful content: application/json: schema: type: array items: $ref: '#/components/schemas/ClusterInfo' "403": $ref: '#/components/responses/Forbidden' /api/v4/brand/image: get: tags: - brand summary: Get brand image description: > Get the previously uploaded brand image. Returns 404 if no brand image has been uploaded. ##### Permissions No permission required. operationId: GetBrandImage responses: "200": description: Brand image retrieval successful content: application/json: schema: type: string "404": $ref: '#/components/responses/NotFound' "501": $ref: '#/components/responses/NotImplemented' post: tags: - brand summary: Upload brand image description: | Uploads a brand image. ##### Permissions Must have `manage_system` permission. operationId: UploadBrandImage requestBody: content: multipart/form-data: schema: type: object properties: image: description: The image to be uploaded type: string format: binary required: - image responses: "201": description: Brand image upload successful content: application/json: schema: $ref: '#/components/schemas/StatusOK' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "413": $ref: '#/components/responses/TooLarge' "501": $ref: '#/components/responses/NotImplemented' delete: tags: - brand summary: Delete current brand image description: > Deletes the previously uploaded brand image. Returns 404 if no brand image has been uploaded. ##### Permissions Must have `manage_system` permission. __Minimum server version: 5.6__ operationId: DeleteBrandImage responses: "200": description: Brand image succesfully deleted content: application/json: schema: $ref: '#/components/schemas/StatusOK' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' /api/v4/commands: post: tags: - commands summary: Create a command description: | Create a command for a team. ##### Permissions `manage_slash_commands` for the team the command is in. operationId: CreateCommand requestBody: content: application/json: schema: type: object required: - team_id - method - trigger - url properties: team_id: type: string description: Team ID to where the command should be created method: type: string description: "`'P'` for post request, `'G'` for get request" trigger: type: string description: Activation word to trigger the command url: type: string description: The URL that the command will make the request description: command to be created required: true responses: "201": description: Command creation successful content: application/json: schema: $ref: '#/components/schemas/Command' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "501": $ref: '#/components/responses/NotImplemented' get: tags: - commands summary: List commands for a team description: | List commands for a team. ##### Permissions `manage_slash_commands` if need list custom commands. operationId: ListCommands parameters: - name: team_id in: query description: The team id. schema: type: string - name: custom_only in: query description: > To get only the custom commands. If set to false will get the custom if the user have access plus the system commands, otherwise just the system commands. schema: type: boolean default: false responses: "200": description: List Commands retrieve successful content: application/json: schema: type: array items: $ref: '#/components/schemas/Command' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "501": $ref: '#/components/responses/NotImplemented' /api/v4/teams/{team_id}/commands/autocomplete: get: tags: - commands summary: List autocomplete commands description: | List autocomplete commands in the team. ##### Permissions `view_team` for the team. operationId: ListAutocompleteCommands parameters: - name: team_id in: path description: Team GUID required: true schema: type: string responses: "200": description: Autocomplete commands retrieval successful content: application/json: schema: type: array items: $ref: '#/components/schemas/Command' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' /api/v4/teams/{team_id}/commands/autocomplete_suggestions: get: tags: - commands summary: List commands' autocomplete data description: | List commands' autocomplete data for the team. ##### Permissions `view_team` for the team. __Minimum server version__: 5.24 operationId: ListCommandAutocompleteSuggestions parameters: - name: team_id in: path description: Team GUID required: true schema: type: string - name: user_input in: query description: String inputted by the user. required: true schema: type: string responses: "200": description: Commands' autocomplete data retrieval successful content: application/json: schema: type: array items: $ref: '#/components/schemas/AutocompleteSuggestion' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' /api/v4/commands/{command_id}: get: tags: - commands summary: Get a command description: > Get a command definition based on command id string. ##### Permissions Must have `manage_slash_commands` permission for the team the command is in. __Minimum server version__: 5.22 operationId: GetCommandById parameters: - in: path name: command_id description: ID of the command to get required: true schema: type: string responses: "200": description: Command get successful content: application/json: schema: $ref: '#/components/schemas/Command' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "404": $ref: '#/components/responses/NotFound' put: tags: - commands summary: Update a command description: > Update a single command based on command id string and Command struct. ##### Permissions Must have `manage_slash_commands` permission for the team the command is in. operationId: UpdateCommand parameters: - in: path name: command_id description: ID of the command to update required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/Command' required: true responses: "200": description: Command updated successful content: application/json: schema: $ref: '#/components/schemas/Command' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' delete: tags: - commands summary: Delete a command description: > Delete a command based on command id string. ##### Permissions Must have `manage_slash_commands` permission for the team the command is in. operationId: DeleteCommand parameters: - in: path name: command_id description: ID of the command to delete required: true schema: type: string responses: "200": description: Command 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' "404": $ref: '#/components/responses/NotFound' /api/v4/commands/{command_id}/move: put: tags: - commands summary: Move a command description: > Move a command to a different team based on command id string. ##### Permissions Must have `manage_slash_commands` permission for the team the command is currently in and the destination team. __Minimum server version__: 5.22 operationId: MoveCommand parameters: - in: path name: command_id description: ID of the command to move required: true schema: type: string requestBody: content: application/json: schema: type: object properties: team_id: type: string description: Destination teamId required: true responses: "200": description: Command move 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/commands/{command_id}/regen_token: put: tags: - commands summary: Generate a new token description: > Generate a new token for the command based on command id string. ##### Permissions Must have `manage_slash_commands` permission for the team the command is in. operationId: RegenCommandToken parameters: - in: path name: command_id description: ID of the command to generate the new token required: true schema: type: string responses: "200": description: Token generation successful content: application/json: schema: type: object properties: token: description: The new token type: string "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' /api/v4/commands/execute: post: tags: - commands summary: Execute a command description: > Execute a command on a team. ##### Permissions Must have `use_slash_commands` permission for the team the command is in. operationId: ExecuteCommand requestBody: content: application/json: schema: type: object required: - channel_id - command properties: channel_id: type: string description: Channel Id where the command will execute command: type: string description: "The slash command to execute, including parameters. Eg, `'/echo bounces around the room'`" description: command to be executed required: true responses: "200": description: Command execution successful content: application/json: schema: $ref: '#/components/schemas/CommandResponse' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "501": $ref: '#/components/responses/NotImplemented' /api/v4/oauth/apps: post: tags: - OAuth summary: Register OAuth app description: > Register an OAuth 2.0 client application with Mattermost as the service provider. ##### Permissions Must have `manage_oauth` permission. operationId: CreateOAuthApp requestBody: content: application/json: schema: type: object required: - name - description - callback_urls - homepage properties: name: type: string description: The name of the client application description: type: string description: A short description of the application icon_url: type: string description: A URL to an icon to display with the application callback_urls: type: array items: type: string description: A list of callback URLs for the appliation homepage: type: string description: A link to the website of the application is_trusted: type: boolean description: Set this to `true` to skip asking users for permission description: OAuth application to register required: true responses: "201": description: App registration successful content: application/json: schema: $ref: '#/components/schemas/OAuthApp' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "501": $ref: '#/components/responses/NotImplemented' get: tags: - OAuth summary: Get OAuth apps description: > Get a page of OAuth 2.0 client applications registered with Mattermost. ##### Permissions With `manage_oauth` permission, the apps registered by the logged in user are returned. With `manage_system_wide_oauth` permission, all apps regardless of creator are returned. operationId: GetOAuthApps parameters: - name: page in: query description: The page to select. schema: type: integer default: 0 - name: per_page in: query description: The number of apps per page. schema: type: integer default: 60 responses: "200": description: OAuthApp list retrieval successful content: application/json: schema: type: array items: $ref: '#/components/schemas/OAuthApp' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "501": $ref: '#/components/responses/NotImplemented' /api/v4/oauth/apps/{app_id}: get: tags: - OAuth summary: Get an OAuth app description: > Get an OAuth 2.0 client application registered with Mattermost. ##### Permissions If app creator, must have `mange_oauth` permission otherwise `manage_system_wide_oauth` permission is required. operationId: GetOAuthApp parameters: - name: app_id in: path description: Application client id required: true schema: type: string responses: "200": description: App retrieval successful content: application/json: schema: $ref: '#/components/schemas/OAuthApp' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "501": $ref: '#/components/responses/NotImplemented' put: tags: - OAuth summary: Update an OAuth app description: > Update an OAuth 2.0 client application based on OAuth struct. ##### Permissions If app creator, must have `mange_oauth` permission otherwise `manage_system_wide_oauth` permission is required. operationId: UpdateOAuthApp parameters: - name: app_id in: path description: Application client id required: true schema: type: string requestBody: content: application/json: schema: type: object required: - id - name - description - callback_urls - homepage properties: id: type: string description: The id of the client application name: type: string description: The name of the client application description: type: string description: A short description of the application icon_url: type: string description: A URL to an icon to display with the application callback_urls: type: array items: type: string description: A list of callback URLs for the appliation homepage: type: string description: A link to the website of the application is_trusted: type: boolean description: Set this to `true` to skip asking users for permission. It will be set to false if value is not provided. description: OAuth application to update required: true responses: "200": description: App update successful content: application/json: schema: $ref: '#/components/schemas/OAuthApp' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "501": $ref: '#/components/responses/NotImplemented' delete: tags: - OAuth summary: Delete an OAuth app description: "Delete and unregister an OAuth 2.0 client application \n##### Permissions\nIf app creator, must have `mange_oauth` permission otherwise `manage_system_wide_oauth` permission is required.\n" operationId: DeleteOAuthApp parameters: - name: app_id in: path description: Application client id required: true schema: type: string responses: "200": description: App 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' "404": $ref: '#/components/responses/NotFound' "501": $ref: '#/components/responses/NotImplemented' /api/v4/oauth/apps/{app_id}/regen_secret: post: tags: - OAuth summary: Regenerate OAuth app secret description: > Regenerate the client secret for an OAuth 2.0 client application registered with Mattermost. ##### Permissions If app creator, must have `mange_oauth` permission otherwise `manage_system_wide_oauth` permission is required. operationId: RegenerateOAuthAppSecret parameters: - name: app_id in: path description: Application client id required: true schema: type: string responses: "200": description: Secret regeneration successful content: application/json: schema: $ref: '#/components/schemas/OAuthApp' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "501": $ref: '#/components/responses/NotImplemented' /api/v4/oauth/apps/{app_id}/info: get: tags: - OAuth summary: Get info on an OAuth app description: > Get public information about an OAuth 2.0 client application registered with Mattermost. The application's client secret will be blanked out. ##### Permissions Must be authenticated. operationId: GetOAuthAppInfo parameters: - name: app_id in: path description: Application client id required: true schema: type: string responses: "200": description: App retrieval successful content: application/json: schema: $ref: '#/components/schemas/OAuthApp' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "404": $ref: '#/components/responses/NotFound' "501": $ref: '#/components/responses/NotImplemented' /api/v4/users/{user_id}/oauth/apps/authorized: get: tags: - OAuth summary: Get authorized OAuth apps description: > Get a page of OAuth 2.0 client applications authorized to access a user's account. ##### Permissions Must be authenticated as the user or have `edit_other_users` permission. operationId: GetAuthorizedOAuthAppsForUser parameters: - name: user_id in: path description: User 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 apps per page. schema: type: integer default: 60 responses: "200": description: OAuthApp list retrieval successful content: application/json: schema: type: array items: $ref: '#/components/schemas/OAuthApp' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "501": $ref: '#/components/responses/NotImplemented' /api/v4/elasticsearch/test: post: tags: - elasticsearch summary: Test Elasticsearch configuration description: > Test the current Elasticsearch configuration to see if the Elasticsearch server can be contacted successfully. Optionally provide a configuration in the request body to test. If no valid configuration is present in the request body the current server configuration will be tested. __Minimum server version__: 4.1 ##### Permissions Must have `manage_system` permission. operationId: TestElasticsearch responses: "200": description: Elasticsearch test successful content: application/json: schema: $ref: '#/components/schemas/StatusOK' "400": $ref: '#/components/responses/BadRequest' "500": $ref: '#/components/responses/InternalServerError' "501": $ref: '#/components/responses/NotImplemented' /api/v4/elasticsearch/purge_indexes: post: tags: - elasticsearch summary: Purge all Elasticsearch indexes description: > Deletes all Elasticsearch indexes and their contents. After calling this endpoint, it is necessary to schedule a new Elasticsearch indexing job to repopulate the indexes. __Minimum server version__: 4.1 ##### Permissions Must have `manage_system` permission. operationId: PurgeElasticsearchIndexes responses: "200": description: Indexes purged successfully. content: application/json: schema: $ref: '#/components/schemas/StatusOK' "500": $ref: '#/components/responses/InternalServerError' "501": $ref: '#/components/responses/NotImplemented' /api/v4/bleve/purge_indexes: post: tags: - bleve summary: Purge all Bleve indexes description: > Deletes all Bleve indexes and their contents. After calling this endpoint, it is necessary to schedule a new Bleve indexing job to repopulate the indexes. __Minimum server version__: 5.24 ##### Permissions Must have `sysconsole_write_experimental` permission. operationId: PurgeBleveIndexes responses: "200": description: Indexes purged successfully. content: application/json: schema: $ref: '#/components/schemas/StatusOK' "500": $ref: '#/components/responses/InternalServerError' "501": $ref: '#/components/responses/NotImplemented' /api/v4/data_retention/policy: get: tags: - data retention summary: Get the global data retention policy description: | Gets the current global data retention policy details from the server, including what data should be purged and the cutoff times for each data type that should be purged. __Minimum server version__: 4.3 ##### Permissions Requires an active session but no other permissions. ##### License Requires an E20 license. operationId: GetDataRetentionPolicy responses: "200": description: Global data retention policy details retrieved successfully. content: application/json: schema: $ref: '#/components/schemas/GlobalDataRetentionPolicy' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "500": $ref: '#/components/responses/InternalServerError' "501": $ref: '#/components/responses/NotImplemented' /api/v4/data_retention/policies_count: get: tags: - data retention summary: Get the number of granular data retention policies description: | Gets the number of granular (i.e. team or channel-specific) data retention policies from the server. __Minimum server version__: 5.35 ##### Permissions Must have the `sysconsole_read_compliance_data_retention` permission. ##### License Requires an E20 license. operationId: GetDataRetentionPoliciesCount responses: "200": description: Number of retention policies retrieved successfully. content: application/json: schema: type: object properties: total_count: type: integer description: The number of granular retention policies. "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "500": $ref: '#/components/responses/InternalServerError' "501": $ref: '#/components/responses/NotImplemented' /api/v4/data_retention/policies: get: tags: - data retention summary: Get the granular data retention policies description: | Gets details about the granular (i.e. team or channel-specific) data retention policies from the server. __Minimum server version__: 5.35 ##### Permissions Must have the `sysconsole_read_compliance_data_retention` permission. ##### License Requires an E20 license. operationId: GetDataRetentionPolicies parameters: - name: page in: query description: The page to select. schema: type: integer default: 0 - name: per_page in: query description: The number of policies per page. There is a maximum limit of 200 per page. schema: type: integer default: 60 responses: "200": description: Retention policies' details retrieved successfully. content: application/json: schema: type: array items: $ref: '#/components/schemas/DataRetentionPolicyWithTeamAndChannelCounts' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "500": $ref: '#/components/responses/InternalServerError' "501": $ref: '#/components/responses/NotImplemented' post: tags: - data retention summary: Create a new granular data retention policy description: | Creates a new granular data retention policy with the specified display name and post duration. __Minimum server version__: 5.35 ##### Permissions Must have the `sysconsole_write_compliance_data_retention` permission. ##### License Requires an E20 license. operationId: CreateDataRetentionPolicy requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DataRetentionPolicyCreate' responses: "201": description: Retention policy successfully created. content: application/json: schema: $ref: '#/components/schemas/DataRetentionPolicyWithTeamAndChannelCounts' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "500": $ref: '#/components/responses/InternalServerError' "501": $ref: '#/components/responses/NotImplemented' /api/v4/data_retention/policies/{policy_id}: get: tags: - data retention summary: Get a granular data retention policy description: | Gets details about a granular data retention policies by ID. __Minimum server version__: 5.35 ##### Permissions Must have the `sysconsole_read_compliance_data_retention` permission. ##### License Requires an E20 license. operationId: GetDataRetentionPolicyByID parameters: - name: policy_id in: path description: The ID of the granular retention policy. required: true schema: type: string responses: "200": description: Retention policy's details retrieved successfully. content: application/json: schema: $ref: '#/components/schemas/DataRetentionPolicyWithTeamAndChannelCounts' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "500": $ref: '#/components/responses/InternalServerError' "501": $ref: '#/components/responses/NotImplemented' patch: tags: - data retention summary: Patch a granular data retention policy description: | Patches (i.e. replaces the fields of) a granular data retention policy. If any fields are omitted, they will not be changed. __Minimum server version__: 5.35 ##### Permissions Must have the `sysconsole_write_compliance_data_retention` permission. ##### License Requires an E20 license. operationId: PatchDataRetentionPolicy parameters: - name: policy_id in: path description: The ID of the granular retention policy. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DataRetentionPolicyWithTeamAndChannelIds' responses: "200": description: Retention policy successfully patched. content: application/json: schema: $ref: '#/components/schemas/DataRetentionPolicyWithTeamAndChannelCounts' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "500": $ref: '#/components/responses/InternalServerError' "501": $ref: '#/components/responses/NotImplemented' delete: tags: - data retention summary: Delete a granular data retention policy description: | Deletes a granular data retention policy. __Minimum server version__: 5.35 ##### Permissions Must have the `sysconsole_write_compliance_data_retention` permission. ##### License Requires an E20 license. operationId: DeleteDataRetentionPolicy parameters: - name: policy_id in: path description: The ID of the granular retention policy. required: true schema: type: string responses: "200": description: Retention policy successfully deleted. content: application/json: schema: $ref: '#/components/schemas/StatusOK' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "500": $ref: '#/components/responses/InternalServerError' "501": $ref: '#/components/responses/NotImplemented' /api/v4/data_retention/policies/{policy_id}/teams: get: tags: - data retention summary: Get the teams for a granular data retention policy description: | Gets the teams to which a granular data retention policy is applied. __Minimum server version__: 5.35 ##### Permissions Must have the `sysconsole_read_compliance_data_retention` permission. ##### License Requires an E20 license. operationId: GetTeamsForRetentionPolicy parameters: - name: policy_id in: path description: The ID of the granular retention policy. 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 teams per page. There is a maximum limit of 200 per page. schema: type: integer default: 60 responses: "200": description: Teams for retention policy successfully retrieved. content: application/json: schema: type: array items: $ref: '#/components/schemas/Team' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "500": $ref: '#/components/responses/InternalServerError' "501": $ref: '#/components/responses/NotImplemented' post: tags: - data retention summary: Add teams to a granular data retention policy description: | Adds teams to a granular data retention policy. __Minimum server version__: 5.35 ##### Permissions Must have the `sysconsole_write_compliance_data_retention` permission. ##### License Requires an E20 license. operationId: AddTeamsToRetentionPolicy parameters: - name: policy_id in: path description: The ID of the granular retention policy. required: true schema: type: string requestBody: required: true content: application/json: schema: type: array items: type: string description: The IDs of the teams to add to the policy. responses: "200": description: Teams successfully added to retention policy. content: application/json: schema: $ref: '#/components/schemas/StatusOK' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "500": $ref: '#/components/responses/InternalServerError' "501": $ref: '#/components/responses/NotImplemented' delete: tags: - data retention summary: Delete teams from a granular data retention policy description: | Delete teams from a granular data retention policy. __Minimum server version__: 5.35 ##### Permissions Must have the `sysconsole_write_compliance_data_retention` permission. ##### License Requires an E20 license. operationId: RemoveTeamsFromRetentionPolicy parameters: - name: policy_id in: path description: The ID of the granular retention policy. required: true schema: type: string requestBody: required: true content: application/json: schema: type: array items: type: string description: The IDs of the teams to remove from the policy. responses: "200": description: Teams successfully deleted from retention policy. content: application/json: schema: $ref: '#/components/schemas/StatusOK' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "500": $ref: '#/components/responses/InternalServerError' "501": $ref: '#/components/responses/NotImplemented' /api/v4/data_retention/policies/{policy_id}/teams/search: post: tags: - data retention summary: Search for the teams in a granular data retention policy description: | Searches for the teams to which a granular data retention policy is applied. __Minimum server version__: 5.35 ##### Permissions Must have the `sysconsole_read_compliance_data_retention` permission. ##### License Requires an E20 license. operationId: SearchTeamsForRetentionPolicy parameters: - name: policy_id in: path description: The ID of the granular retention policy. required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: term: type: string description: The search term to match against the name or display name of teams responses: "200": description: Teams for retention policy successfully retrieved. content: application/json: schema: type: array items: $ref: '#/components/schemas/Team' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "500": $ref: '#/components/responses/InternalServerError' "501": $ref: '#/components/responses/NotImplemented' /api/v4/data_retention/policies/{policy_id}/channels: get: tags: - data retention summary: Get the channels for a granular data retention policy description: | Gets the channels to which a granular data retention policy is applied. __Minimum server version__: 5.35 ##### Permissions Must have the `sysconsole_read_compliance_data_retention` permission. ##### License Requires an E20 license. operationId: GetChannelsForRetentionPolicy parameters: - name: policy_id in: path description: The ID of the granular retention policy. 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 channels per page. There is a maximum limit of 200 per page. schema: type: integer default: 60 responses: "200": description: Channels for retention policy successfully retrieved. content: application/json: schema: $ref: '#/components/schemas/ChannelListWithTeamData' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "500": $ref: '#/components/responses/InternalServerError' "501": $ref: '#/components/responses/NotImplemented' post: tags: - data retention summary: Add channels to a granular data retention policy description: | Adds channels to a granular data retention policy. __Minimum server version__: 5.35 ##### Permissions Must have the `sysconsole_write_compliance_data_retention` permission. ##### License Requires an E20 license. operationId: AddChannelsToRetentionPolicy parameters: - name: policy_id in: path description: The ID of the granular retention policy. required: true schema: type: string requestBody: required: true content: application/json: schema: type: array items: type: string description: The IDs of the channels to add to the policy. responses: "200": description: Channels successfully added to retention policy. content: application/json: schema: $ref: '#/components/schemas/StatusOK' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "500": $ref: '#/components/responses/InternalServerError' "501": $ref: '#/components/responses/NotImplemented' delete: tags: - data retention summary: Delete channels from a granular data retention policy description: | Delete channels from a granular data retention policy. __Minimum server version__: 5.35 ##### Permissions Must have the `sysconsole_write_compliance_data_retention` permission. ##### License Requires an E20 license. operationId: RemoveChannelsFromRetentionPolicy parameters: - name: policy_id in: path description: The ID of the granular retention policy. required: true schema: type: string requestBody: required: true content: application/json: schema: type: array items: type: string description: The IDs of the channels to add to the policy. responses: "200": description: Channels successfully deleted from retention policy. content: application/json: schema: $ref: '#/components/schemas/StatusOK' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "500": $ref: '#/components/responses/InternalServerError' "501": $ref: '#/components/responses/NotImplemented' /api/v4/data_retention/policies/{policy_id}/channels/search: post: tags: - data retention summary: Search for the channels in a granular data retention policy description: | Searches for the channels to which a granular data retention policy is applied. __Minimum server version__: 5.35 ##### Permissions Must have the `sysconsole_read_compliance_data_retention` permission. ##### License Requires an E20 license. operationId: SearchChannelsForRetentionPolicy parameters: - name: policy_id in: path description: The ID of the granular retention policy. required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: term: type: string description: The string to search in the channel name, display name, and purpose. team_ids: type: array items: type: string description: > Filters results to channels belonging to the given team ids 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 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 deleted: type: boolean description: > Filters results to only return deleted / archived channels responses: "200": description: Channels for retention policy successfully retrieved. content: application/json: schema: $ref: '#/components/schemas/ChannelListWithTeamData' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "500": $ref: '#/components/responses/InternalServerError' "501": $ref: '#/components/responses/NotImplemented' /api/v4/plugins: post: tags: - plugins summary: Upload plugin description: > Upload a plugin that is contained within a compressed .tar.gz file. Plugins and plugin uploads must be enabled in the server's config settings. ##### Permissions Must have `manage_system` permission. __Minimum server version__: 4.4 operationId: UploadPlugin requestBody: content: multipart/form-data: schema: type: object properties: plugin: description: The plugin image to be uploaded type: string format: binary force: description: Set to 'true' to overwrite a previously installed plugin with the same ID, if any type: string required: - plugin responses: "201": description: Plugin upload successful content: application/json: schema: $ref: '#/components/schemas/StatusOK' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "413": $ref: '#/components/responses/TooLarge' "501": $ref: '#/components/responses/NotImplemented' get: tags: - plugins summary: Get plugins description: > Get a list of inactive and a list of active plugin manifests. Plugins must be enabled in the server's config settings. ##### Permissions Must have `manage_system` permission. __Minimum server version__: 4.4 operationId: GetPlugins responses: "200": description: Plugins retrieval successful content: application/json: schema: type: object properties: active: type: array items: $ref: '#/components/schemas/PluginManifest' inactive: type: array items: $ref: '#/components/schemas/PluginManifest' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "501": $ref: '#/components/responses/NotImplemented' /api/v4/plugins/install_from_url: post: tags: - plugins summary: Install plugin from url description: > Supply a URL to a plugin compressed in a .tar.gz file. Plugins must be enabled in the server's config settings. ##### Permissions Must have `manage_system` permission. __Minimum server version__: 5.14 operationId: InstallPluginFromUrl parameters: - name: plugin_download_url in: query description: URL used to download the plugin required: true schema: type: string - name: force in: query description: Set to 'true' to overwrite a previously installed plugin with the same ID, if any schema: type: string responses: "201": description: Plugin install successful content: application/json: schema: $ref: '#/components/schemas/StatusOK' "400": $ref: '#/components/responses/BadRequest' "403": $ref: '#/components/responses/Forbidden' "501": $ref: '#/components/responses/NotImplemented' /api/v4/plugins/{plugin_id}: delete: tags: - plugins summary: Remove plugin description: > Remove the plugin with the provided ID from the server. All plugin files are deleted. Plugins must be enabled in the server's config settings. ##### Permissions Must have `manage_system` permission. __Minimum server version__: 4.4 operationId: RemovePlugin parameters: - name: plugin_id description: Id of the plugin to be removed in: path required: true schema: type: string responses: "200": description: Plugin removed 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' "501": $ref: '#/components/responses/NotImplemented' /api/v4/plugins/{plugin_id}/enable: post: tags: - plugins summary: Enable plugin description: > Enable a previously uploaded plugin. Plugins must be enabled in the server's config settings. ##### Permissions Must have `manage_system` permission. __Minimum server version__: 4.4 operationId: EnablePlugin parameters: - name: plugin_id description: Id of the plugin to be enabled in: path required: true schema: type: string responses: "200": description: Plugin enabled 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' "501": $ref: '#/components/responses/NotImplemented' /api/v4/plugins/{plugin_id}/disable: post: tags: - plugins summary: Disable plugin description: > Disable a previously enabled plugin. Plugins must be enabled in the server's config settings. ##### Permissions Must have `manage_system` permission. __Minimum server version__: 4.4 operationId: DisablePlugin parameters: - name: plugin_id description: Id of the plugin to be disabled in: path required: true schema: type: string responses: "200": description: Plugin disabled 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' "501": $ref: '#/components/responses/NotImplemented' /api/v4/plugins/webapp: get: tags: - plugins summary: Get webapp plugins description: | Get a list of web app plugins installed and activated on the server. ##### Permissions No permissions required. __Minimum server version__: 4.4 operationId: GetWebappPlugins responses: "200": description: Plugin deactivated successfully content: application/json: schema: type: array items: $ref: '#/components/schemas/PluginManifestWebapp' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "501": $ref: '#/components/responses/NotImplemented' /api/v4/plugins/statuses: get: tags: - plugins summary: Get plugins status description: | Returns the status for plugins installed anywhere in the cluster ##### Permissions No permissions required. __Minimum server version__: 4.4 operationId: GetPluginStatuses responses: "200": description: Plugin status retreived successfully content: application/json: schema: type: array items: $ref: '#/components/schemas/PluginStatus' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "501": $ref: '#/components/responses/NotImplemented' /api/v4/plugins/marketplace: post: tags: - plugins summary: Installs a marketplace plugin description: | Installs a plugin listed in the marketplace server. ##### Permissions Must have `manage_system` permission. __Minimum server version__: 5.16 operationId: InstallMarketplacePlugin requestBody: content: application/json: schema: type: object required: - id - version properties: id: type: string description: The ID of the plugin to install. version: type: string description: The version of the plugin to install. description: The metadata identifying the plugin to install. required: true responses: "200": description: Plugin installed successfully content: application/json: schema: $ref: '#/components/schemas/PluginManifest' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "501": $ref: '#/components/responses/NotImplemented' get: tags: - plugins summary: Gets all the marketplace plugins description: > Gets all plugins from the marketplace server, merging data from locally installed plugins as well as prepackaged plugins shipped with the server. ##### Permissions Must have `manage_system` permission. __Minimum server version__: 5.16 operationId: GetMarketplacePlugins parameters: - name: page in: query description: Page number to be fetched. (not yet implemented) schema: type: integer - name: per_page in: query description: Number of item per page. (not yet implemented) schema: type: integer - name: filter in: query description: Set to filter plugins by ID, name, or description. schema: type: string - name: server_version in: query description: Set to filter minimum plugin server version. (not yet implemented) schema: type: string - name: local_only in: query description: Set true to only retrieve local plugins. schema: type: boolean responses: "200": description: Plugins retrieval successful content: application/json: schema: type: array items: $ref: '#/components/schemas/MarketplacePlugin' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "501": $ref: '#/components/responses/NotImplemented' /api/v4/plugins/marketplace/first_admin_visit: get: tags: - plugins summary: Get if the Plugin Marketplace has been visited by at least an admin. description: | Retrieves the status that specifies that at least one System Admin has visited the in-product Plugin Marketplace. __Minimum server version: 5.33__ ##### Permissions Must have `manage_system` permissions. operationId: GetMarketplaceVisitedByAdmin responses: "200": description: Retrieves the system-level status content: application/json: schema: $ref: '#/components/schemas/System' "403": $ref: '#/components/responses/Forbidden' "500": $ref: '#/components/responses/InternalServerError' post: tags: - system summary: Stores that the Plugin Marketplace has been visited by at least an admin. description: | Stores the system-level status that specifies that at least an admin has visited the in-product Plugin Marketplace. __Minimum server version: 5.33__ ##### Permissions Must have `manage_system` permissions. operationId: UpdateMarketplaceVisitedByAdmin requestBody: content: application/json: schema: $ref: '#/components/schemas/System' required: true responses: "200": description: setting has been successfully set content: application/json: schema: $ref: '#/components/schemas/StatusOK' "403": $ref: '#/components/responses/Forbidden' "500": $ref: '#/components/responses/InternalServerError' /api/v4/roles: get: tags: - roles summary: Get a list of all the roles description: | ##### Permissions `manage_system` permission is required. __Minimum server version__: 5.33 operationId: GetAllRoles responses: "200": description: Roles retrieval successful content: application/json: schema: type: array items: $ref: '#/components/schemas/Role' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' /api/v4/roles/{role_id}: get: tags: - roles summary: Get a role description: | Get a role from the provided role id. ##### Permissions Requires an active session but no other permissions. __Minimum server version__: 4.9 operationId: GetRole parameters: - name: role_id in: path description: Role GUID required: true schema: type: string responses: "200": description: Role retrieval successful content: application/json: schema: $ref: '#/components/schemas/Role' "401": $ref: '#/components/responses/Unauthorized' "404": $ref: '#/components/responses/NotFound' /api/v4/roles/name/{role_name}: get: tags: - roles summary: Get a role description: | Get a role from the provided role name. ##### Permissions Requires an active session but no other permissions. __Minimum server version__: 4.9 operationId: GetRoleByName parameters: - name: role_name in: path description: Role Name required: true schema: type: string responses: "200": description: Role retrieval successful content: application/json: schema: $ref: '#/components/schemas/Role' "401": $ref: '#/components/responses/Unauthorized' "404": $ref: '#/components/responses/NotFound' /api/v4/roles/{role_id}/patch: put: tags: - roles summary: Patch a role description: > Partially update a role by providing only the fields you want to update. Omitted fields will not be updated. The fields that can be updated are defined in the request body, all other provided fields will be ignored. ##### Permissions `manage_system` permission is required. __Minimum server version__: 4.9 operationId: PatchRole parameters: - name: role_id in: path description: Role GUID required: true schema: type: string requestBody: content: application/json: schema: type: object properties: permissions: type: array items: type: string description: The permissions the role should grant. description: Role object to be updated required: true responses: "200": description: Role patch successful content: application/json: schema: $ref: '#/components/schemas/Role' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' /api/v4/roles/names: post: tags: - roles summary: Get a list of roles by name description: | Get a list of roles from their names. ##### Permissions Requires an active session but no other permissions. __Minimum server version__: 4.9 operationId: GetRolesByNames requestBody: content: application/json: schema: type: array items: type: string description: List of role names required: true responses: "200": description: Role list retrieval successful content: application/json: schema: type: array items: $ref: '#/components/schemas/Role' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "404": $ref: '#/components/responses/NotFound' /api/v4/schemes: get: tags: - schemes summary: Get the schemes. description: > Get a page of schemes. Use the query parameters to modify the behaviour of this endpoint. ##### Permissions Must have `manage_system` permission. __Minimum server version__: 5.0 operationId: GetSchemes parameters: - name: scope in: query description: Limit the results returned to the provided scope, either `team` or `channel`. 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 schemes per page. schema: type: integer default: 60 responses: "200": description: Scheme list retrieval successful content: application/json: schema: type: array items: $ref: '#/components/schemas/Scheme' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' post: tags: - schemes summary: Create a scheme description: | Create a new scheme. ##### Permissions Must have `manage_system` permission. __Minimum server version__: 5.0 operationId: CreateScheme requestBody: content: application/json: schema: type: object required: - name - scope properties: name: type: string description: The name of the scheme description: type: string description: The description of the scheme scope: type: string description: The scope of the scheme ("team" or "channel") description: Scheme object to create required: true responses: "201": description: Scheme creation successful content: application/json: schema: $ref: '#/components/schemas/Scheme' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "501": $ref: '#/components/responses/NotImplemented' /api/v4/schemes/{scheme_id}: get: tags: - schemes summary: Get a scheme description: | Get a scheme from the provided scheme id. ##### Permissions Must have `manage_system` permission. __Minimum server version__: 5.0 operationId: GetScheme parameters: - name: scheme_id in: path description: Scheme GUID required: true schema: type: string responses: "200": description: Scheme retrieval successful content: application/json: schema: $ref: '#/components/schemas/Scheme' "401": $ref: '#/components/responses/Unauthorized' "404": $ref: '#/components/responses/NotFound' "501": $ref: '#/components/responses/NotImplemented' delete: tags: - schemes summary: Delete a scheme description: | Soft deletes a scheme, by marking the scheme as deleted in the database. ##### Permissions Must have `manage_system` permission. __Minimum server version__: 5.0 operationId: DeleteScheme parameters: - name: scheme_id in: path description: ID of the scheme to delete required: true schema: type: string responses: "200": description: Scheme 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' "501": $ref: '#/components/responses/NotImplemented' /api/v4/schemes/{scheme_id}/patch: put: tags: - schemes summary: Patch a scheme description: > Partially update a scheme by providing only the fields you want to update. Omitted fields will not be updated. The fields that can be updated are defined in the request body, all other provided fields will be ignored. ##### Permissions `manage_system` permission is required. __Minimum server version__: 5.0 operationId: PatchScheme parameters: - name: scheme_id in: path description: Scheme GUID required: true schema: type: string requestBody: content: application/json: schema: type: object properties: name: type: string description: The human readable name of the scheme description: type: string description: The description of the scheme description: Scheme object to be updated required: true responses: "200": description: Scheme patch successful content: application/json: schema: $ref: '#/components/schemas/Scheme' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "501": $ref: '#/components/responses/NotImplemented' /api/v4/schemes/{scheme_id}/teams: get: tags: - schemes summary: Get a page of teams which use this scheme. description: > Get a page of teams which use this scheme. The provided Scheme ID should be for a Team-scoped Scheme. Use the query parameters to modify the behaviour of this endpoint. ##### Permissions `manage_system` permission is required. __Minimum server version__: 5.0 operationId: GetTeamsForScheme parameters: - name: scheme_id in: path description: Scheme 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 teams per page. schema: type: integer default: 60 responses: "200": description: Team list 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/schemes/{scheme_id}/channels: get: tags: - schemes summary: Get a page of channels which use this scheme. description: > Get a page of channels which use this scheme. The provided Scheme ID should be for a Channel-scoped Scheme. Use the query parameters to modify the behaviour of this endpoint. ##### Permissions `manage_system` permission is required. __Minimum server version__: 5.0 operationId: GetChannelsForScheme parameters: - name: scheme_id in: path description: Scheme 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 channels per page. schema: type: integer default: 60 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' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' /api/v4/terms_of_service: get: tags: - terms of service summary: Get latest terms of service description: | Get latest terms of service from the server __Minimum server version__: 5.4 ##### Permissions Must be authenticated. operationId: GetTermsOfService responses: "200": description: Terms of service fetched successfully content: application/json: schema: $ref: '#/components/schemas/TermsOfService' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' post: tags: - terms of service summary: Creates a new terms of service description: | Creates new terms of service __Minimum server version__: 5.4 ##### Permissions Must have `manage_system` permission. operationId: CreateTermsOfService responses: "200": description: terms of service fetched successfully content: application/json: schema: $ref: '#/components/schemas/TermsOfService' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' /api/v4/sharedchannels/{team_id}: get: tags: - shared channels summary: Get all shared channels for team. description: | Get all shared channels for a team. __Minimum server version__: 5.50 ##### Permissions Must be authenticated. operationId: GetAllSharedChannels parameters: - name: team_id in: path description: Team Id required: true schema: type: string - name: page description: The page to select. in: query schema: type: integer default: 0 - name: per_page description: The number of sharedchannels per page. in: query schema: type: integer default: 0 responses: "200": description: Shared channels fetch successful. Result may be empty. content: application/json: schema: type: array items: $ref: '#/components/schemas/SharedChannel' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' /api/v4/sharedchannels/remote_info/{remote_id}: get: tags: - shared channels summary: Get remote cluster info by ID for user. description: | Get remote cluster info based on remoteId. __Minimum server version__: 5.50 ##### Permissions Must be authenticated and user must belong to at least one channel shared with the remote cluster. operationId: GetRemoteClusterInfo parameters: - name: remote_id in: path description: Remote Cluster GUID required: true schema: type: string responses: "200": description: Remote cluster info retrieval successful content: application/json: schema: $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/reactions: post: tags: - reactions summary: Create a reaction description: | Create a reaction. ##### Permissions Must have `read_channel` permission for the channel the post is in. operationId: SaveReaction requestBody: content: application/json: schema: $ref: '#/components/schemas/Reaction' description: The user's reaction with its post_id, user_id, and emoji_name fields set required: true responses: "201": description: Reaction creation successful content: application/json: schema: $ref: '#/components/schemas/Reaction' "400": $ref: '#/components/responses/BadRequest' "403": $ref: '#/components/responses/Forbidden' /api/v4/posts/{post_id}/reactions: get: tags: - reactions summary: Get a list of reactions to a post description: | Get a list of reactions made by all users to a given post. ##### Permissions Must have `read_channel` permission for the channel the post is in. operationId: GetReactions parameters: - name: post_id in: path description: ID of a post required: true schema: type: string responses: "200": description: List reactions retrieve successful content: application/json: schema: type: array items: $ref: '#/components/schemas/Reaction' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' /api/v4/users/{user_id}/posts/{post_id}/reactions/{emoji_name}: delete: tags: - reactions summary: Remove a reaction from a post description: | Deletes a reaction made by a user from the given post. ##### Permissions Must be user or have `manage_system` permission. operationId: DeleteReaction parameters: - name: user_id in: path description: ID of the user required: true schema: type: string - name: post_id in: path description: ID of the post required: true schema: type: string - name: emoji_name in: path description: emoji name required: true schema: type: string responses: "200": description: Reaction 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/posts/ids/reactions: post: tags: - reactions summary: Bulk get the reaction for posts description: | Get a list of reactions made by all users to a given post. ##### Permissions Must have `read_channel` permission for the channel the post is in. __Minimum server version__: 5.8 operationId: GetBulkReactions requestBody: content: application/json: schema: type: array items: type: string description: Array of post IDs required: true responses: "200": description: Reactions retrieval successful content: application/json: schema: $ref: '#/components/schemas/PostIdToReactionsMap' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' /api/v4/actions/dialogs/open: post: tags: - integration_actions summary: Open a dialog description: > Open an interactive dialog using a trigger ID provided by a slash command, or some other action payload. See https://docs.mattermost.com/developer/interactive-dialogs.html for more information on interactive dialogs. __Minimum server version: 5.6__ operationId: OpenInteractiveDialog requestBody: content: application/json: schema: type: object required: - trigger_id - url - dialog properties: trigger_id: type: string description: Trigger ID provided by other action url: type: string description: The URL to send the submitted dialog payload to dialog: type: object required: - title - elements description: Post object to create properties: callback_id: type: string description: Set an ID that will be included when the dialog is submitted title: type: string description: Title of the dialog introduction_text: type: string description: Markdown formatted introductory paragraph elements: type: array description: Input elements, see https://docs.mattermost.com/developer/interactive-dialogs.html#elements items: type: object submit_label: type: string description: Label on the submit button notify_on_cancel: type: boolean description: Set true to receive payloads when user cancels a dialog state: type: string description: Set some state to be echoed back with the dialog submission description: Metadata for the dialog to be opened required: true responses: "200": description: Dialog open successful content: application/json: schema: $ref: '#/components/schemas/StatusOK' "400": $ref: '#/components/responses/BadRequest' /api/v4/actions/dialogs/submit: post: tags: - integration_actions summary: Submit a dialog description: > Endpoint used by the Mattermost clients to submit a dialog. See https://docs.mattermost.com/developer/interactive-dialogs.html for more information on interactive dialogs. __Minimum server version: 5.6__ operationId: SubmitInteractiveDialog requestBody: content: application/json: schema: type: object required: - url - submission - channel_id - team_id properties: url: type: string description: The URL to send the submitted dialog payload to channel_id: type: string description: Channel ID the user submitted the dialog from team_id: type: string description: Team ID the user submitted the dialog from submission: type: object description: String map where keys are element names and values are the element input values callback_id: type: string description: Callback ID sent when the dialog was opened state: type: string description: State sent when the dialog was opened cancelled: type: boolean description: Set to true if the dialog was cancelled description: Dialog submission data required: true responses: "200": description: Dialog submission 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/bots: post: tags: - bots summary: Create a bot description: | Create a new bot account on the system. Username is required. ##### Permissions Must have `create_bot` permission. __Minimum server version__: 5.10 operationId: CreateBot requestBody: description: Bot to be created required: true content: application/json: schema: type: object required: - username properties: username: type: string display_name: type: string description: type: string responses: "201": description: Bot creation successful content: application/json: schema: $ref: '#/components/schemas/Bot' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' get: tags: - bots summary: Get bots description: > Get a page of a list of bots. ##### Permissions Must have `read_bots` permission for bots you are managing, and `read_others_bots` permission for bots others are managing. __Minimum server version__: 5.10 operationId: GetBots parameters: - 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. There is a maximum limit of 200 users per page. schema: type: integer default: 60 - name: include_deleted in: query description: If deleted bots should be returned. schema: type: boolean - name: only_orphaned in: query description: When true, only orphaned bots will be returned. A bot is considered orphaned if its owner has been deactivated. schema: type: boolean responses: "200": description: Bot page retrieval successful content: application/json: schema: type: array items: $ref: '#/components/schemas/Bot' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' /api/v4/bots/{bot_user_id}: put: tags: - bots summary: Patch a bot description: "Partially update a bot by providing only the fields you want to update. Omitted fields will not be updated. The fields that can be updated are defined in the request body, all other provided fields will be ignored.\n##### Permissions\nMust have `manage_bots` permission. \n__Minimum server version__: 5.10\n" operationId: PatchBot parameters: - name: bot_user_id in: path description: Bot user ID required: true schema: type: string requestBody: description: Bot to be created required: true content: application/json: schema: type: object required: - username properties: username: type: string display_name: type: string description: type: string responses: "200": description: Bot patch successful content: application/json: schema: $ref: '#/components/schemas/Bot' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' get: tags: - bots summary: Get a bot description: > Get a bot specified by its bot id. ##### Permissions Must have `read_bots` permission for bots you are managing, and `read_others_bots` permission for bots others are managing. __Minimum server version__: 5.10 operationId: GetBot parameters: - name: bot_user_id in: path description: Bot user ID required: true schema: type: string - name: include_deleted in: query description: If deleted bots should be returned. schema: type: boolean responses: "200": description: Bot successfully retrieved. content: application/json: schema: $ref: '#/components/schemas/Bot' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' /api/v4/bots/{bot_user_id}/disable: post: tags: - bots summary: Disable a bot description: "Disable a bot.\n##### Permissions\nMust have `manage_bots` permission. \n__Minimum server version__: 5.10\n" operationId: DisableBot parameters: - name: bot_user_id in: path description: Bot user ID required: true schema: type: string responses: "200": description: Bot successfully disabled. content: application/json: schema: $ref: '#/components/schemas/Bot' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' /api/v4/bots/{bot_user_id}/enable: post: tags: - bots summary: Enable a bot description: "Enable a bot.\n##### Permissions\nMust have `manage_bots` permission. \n__Minimum server version__: 5.10\n" operationId: EnableBot parameters: - name: bot_user_id in: path description: Bot user ID required: true schema: type: string responses: "200": description: Bot successfully enabled. content: application/json: schema: $ref: '#/components/schemas/Bot' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' /api/v4/bots/{bot_user_id}/assign/{user_id}: post: tags: - bots summary: Assign a bot to a user description: "Assign a bot to a specified user.\n##### Permissions\nMust have `manage_bots` permission. \n__Minimum server version__: 5.10\n" operationId: AssignBot parameters: - name: bot_user_id in: path description: Bot user ID required: true schema: type: string - name: user_id in: path description: The user ID to assign the bot to. required: true schema: type: string responses: "200": description: Bot successfully assigned. content: application/json: schema: $ref: '#/components/schemas/Bot' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' /api/v4/bots/{bot_user_id}/icon: get: tags: - bots summary: Get bot's LHS icon description: | Get a bot's LHS icon image based on bot_user_id string parameter. ##### Permissions Must be logged in. __Minimum server version__: 5.14 operationId: GetBotIconImage parameters: - name: bot_user_id in: path description: Bot user ID required: true schema: type: string responses: "200": description: Bot's LHS icon image "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' "501": $ref: '#/components/responses/NotImplemented' post: tags: - bots summary: Set bot's LHS icon image description: > Set a bot's LHS icon image based on bot_user_id string parameter. Icon image must be SVG format, all other formats are rejected. ##### Permissions Must have `manage_bots` permission. __Minimum server version__: 5.14 operationId: SetBotIconImage parameters: - name: bot_user_id in: path description: Bot user ID required: true schema: type: string requestBody: content: multipart/form-data: schema: type: object properties: image: description: SVG icon image to be uploaded type: string format: binary required: - image responses: "200": description: SVG icon image set successful content: application/json: schema: $ref: '#/components/schemas/StatusOK' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "413": $ref: '#/components/responses/TooLarge' "500": $ref: '#/components/responses/InternalServerError' "501": $ref: '#/components/responses/NotImplemented' delete: tags: - bots summary: Delete bot's LHS icon image description: | Delete bot's LHS icon image based on bot_user_id string parameter. ##### Permissions Must have `manage_bots` permission. __Minimum server version__: 5.14 operationId: DeleteBotIconImage parameters: - name: bot_user_id in: path description: Bot user ID required: true schema: type: string responses: "200": description: Icon image 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' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' "501": $ref: '#/components/responses/NotImplemented' /api/v4/bots/{bot_user_id}/convert_to_user: post: tags: - bots - users summary: Convert a bot into a user description: | Convert a bot into a user. __Minimum server version__: 5.26 ##### Permissions Must have `manage_system` permission. operationId: ConvertBotToUser parameters: - name: bot_user_id in: path description: Bot user ID required: true schema: type: string - name: set_system_admin in: query description: Whether to give the user the system admin role. schema: type: boolean default: false requestBody: content: application/json: schema: type: object properties: email: type: string username: type: string password: type: string first_name: type: string last_name: type: string nickname: type: string locale: type: string position: type: string props: type: object notify_props: $ref: '#/components/schemas/UserNotifyProps' description: Data to be used in the user creation required: true responses: "200": description: Bot successfully converted 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/cloud/limits: get: tags: - cloud summary: Get cloud workspace limits description: > Retrieve any cloud workspace limits applicable to this instance. ##### Permissions Must be authenticated and be licensed for Cloud. __Minimum server version__: 7.0 __Note:__ This is intended for internal use and is subject to change. operationId: GetCloudLimits responses: "200": description: Cloud workspace limits returned successfully content: application/json: schema: $ref: '#/components/schemas/ProductLimits' "401": $ref: '#/components/responses/Unauthorized' "500": $ref: '#/components/responses/InternalServerError' "501": $ref: '#/components/responses/NotImplemented' /api/v4/cloud/products: get: tags: - cloud summary: Get cloud products description: > Retrieve a list of all products that are offered for Mattermost Cloud. ##### Permissions Must have `manage_system` permission and be licensed for Cloud. __Minimum server version__: 5.28 __Note:__ This is intended for internal use and is subject to change. operationId: GetCloudProducts responses: "200": description: Cloud products returned successfully content: application/json: schema: type: array items: $ref: '#/components/schemas/Product' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "501": $ref: '#/components/responses/NotImplemented' /api/v4/cloud/payment: post: tags: - cloud summary: Create a customer setup payment intent description: | Creates a customer setup payment intent for the given Mattermost cloud installation. ##### Permissions Must have `manage_system` permission and be licensed for Cloud. __Minimum server version__: 5.28 __Note:__: This is intended for internal use and is subject to change. operationId: CreateCustomerPayment responses: "201": description: Payment setup intented created content: application/json: schema: $ref: '#/components/schemas/PaymentSetupIntent' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "501": $ref: '#/components/responses/NotImplemented' /api/v4/cloud/payment/confirm: post: tags: - cloud summary: Completes the payment setup intent description: > Confirms the payment setup intent initiated when posting to `/cloud/payment`. ##### Permissions Must have `manage_system` permission and be licensed for Cloud. __Minimum server version__: 5.28 __Note:__ This is intended for internal use and is subject to change. operationId: ConfirmCustomerPayment requestBody: content: multipart/form-data: schema: type: object properties: stripe_setup_intent_id: type: string responses: "200": description: Payment setup intent confirmed successfully "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "501": $ref: '#/components/responses/NotImplemented' /api/v4/cloud/customer: get: tags: - cloud summary: Get cloud customer description: > Retrieves the customer information for the Mattermost Cloud customer bound to this installation. ##### Permissions Must have `manage_system` permission and be licensed for Cloud. __Minimum server version__: 5.28 __Note:__ This is intended for internal use and is subject to change. operationId: GetCloudCustomer responses: "200": description: Cloud customer returned successfully content: application/json: schema: $ref: '#/components/schemas/CloudCustomer' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "501": $ref: '#/components/responses/NotImplemented' put: tags: - cloud summary: Update cloud customer description: > Updates the customer information for the Mattermost Cloud customer bound to this installation. ##### Permissions Must have `manage_system` permission and be licensed for Cloud. __Minimum server version__: 5.29 __Note:__ This is intended for internal use and is subject to change. operationId: UpdateCloudCustomer requestBody: content: application/json: schema: type: object properties: name: type: string email: type: string contact_first_name: type: string contact_last_name: type: string num_employees: type: string description: Customer patch including information to update required: true responses: "200": description: Cloud customer updated successfully content: application/json: schema: $ref: '#/components/schemas/CloudCustomer' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "501": $ref: '#/components/responses/NotImplemented' /api/v4/cloud/customer/address: put: tags: - cloud summary: Update cloud customer address description: > Updates the company address for the Mattermost Cloud customer bound to this installation. ##### Permissions Must have `manage_system` permission and be licensed for Cloud. __Minimum server version__: 5.29 __Note:__ This is intended for internal use and is subject to change. operationId: UpdateCloudCustomerAddress requestBody: content: application/json: schema: $ref: '#/components/schemas/Address' description: Company address information to update required: true responses: "200": description: Cloud customer address updated successfully content: application/json: schema: $ref: '#/components/schemas/CloudCustomer' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "501": $ref: '#/components/responses/NotImplemented' /api/v4/cloud/subscription: get: tags: - cloud summary: Get cloud subscription description: > Retrieves the subscription information for the Mattermost Cloud customer bound to this installation. ##### Permissions Must have `manage_system` permission and be licensed for Cloud. __Minimum server version__: 5.28 __Note:__ This is intended for internal use and is subject to change. operationId: GetSubscription responses: "200": description: Cloud subscription returned successfully content: application/json: schema: $ref: '#/components/schemas/Subscription' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "501": $ref: '#/components/responses/NotImplemented' /api/v4/cloud/installation: get: tags: - cloud summary: GET endpoint for Installation information description: > An endpoint for fetching the installation information. ##### Permissions Must have `sysconsole_read_site_ip_filters` permission and be licensed for Cloud. __Minimum server version__: 9.1 __Note:__ This is intended for internal use and is subject to change. operationId: GetEndpointForInstallationInformation responses: "200": description: Installation returned successfully content: application/json: schema: $ref: '#/components/schemas/Installation' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "501": $ref: '#/components/responses/NotImplemented' /api/v4/cloud/subscription/invoices: get: tags: - cloud summary: Get cloud subscription invoices description: > Retrieves the invoices for the subscription bound to this installation. ##### Permissions Must have `manage_system` permission and be licensed for Cloud. __Minimum server version__: 5.30 __Note:__ This is intended for internal use and is subject to change. operationId: GetInvoicesForSubscription responses: "200": description: Subscription invoices returned successfully content: application/json: schema: type: array items: $ref: '#/components/schemas/Invoice' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "501": $ref: '#/components/responses/NotImplemented' /api/v4/cloud/subscription/invoices/{invoice_id}/pdf: get: tags: - cloud summary: Get cloud invoice PDF description: > Retrieves the PDF for the invoice passed as parameter ##### Permissions Must have `manage_system` permission and be licensed for Cloud. __Minimum server version__: 5.30 __Note:__ This is intended for internal use and is subject to change. operationId: GetInvoiceForSubscriptionAsPdf parameters: - name: invoice_id in: path description: Invoice ID required: true schema: type: string responses: "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "501": $ref: '#/components/responses/NotImplemented' /api/v4/cloud/webhook: post: tags: - cloud summary: POST endpoint for CWS Webhooks description: > An endpoint for processing webhooks from the Customer Portal ##### Permissions This endpoint should only be accessed by CWS, in a Mattermost Cloud instance __Minimum server version__: 5.30 __Note:__ This is intended for internal use and is subject to change. operationId: PostEndpointForCwsWebhooks responses: "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "501": $ref: '#/components/responses/NotImplemented' /api/v4/usage/posts: get: tags: - usage summary: Get current usage of posts description: > Retrieve rounded off total no. of posts for this instance. Example: returns 4000 instead of 4321 ##### Permissions Must be authenticated. __Minimum server version__: 7.0 operationId: GetPostsUsage responses: "200": description: Total no. of posts returned successfully content: application/json: schema: $ref: '#/components/schemas/PostsUsage' "401": $ref: '#/components/responses/Unauthorized' "500": $ref: '#/components/responses/InternalServerError' /api/v4/usage/storage: get: tags: - usage summary: Get the total file storage usage for the instance in bytes. description: > Get the total file storage usage for the instance in bytes rounded down to the most significant digit. Example: returns 4000 instead of 4321 ##### Permissions Must be authenticated. __Minimum server version__: 7.1 operationId: GetStorageUsage responses: "200": description: The total file storage usage for the instance in bytes rounded down to the most significant digit. content: application/json: schema: $ref: '#/components/schemas/StorageUsage' "401": $ref: '#/components/responses/Unauthorized' "500": $ref: '#/components/responses/InternalServerError' /api/v4/permissions/ancillary: get: tags: - permissions summary: Return all system console subsection ancillary permissions description: > Returns all the ancillary permissions for the corresponding system console subsection permissions appended to the requested permission subsections. __Minimum server version__: 5.35 operationId: GetAncillaryPermissions parameters: - name: subsection_permissions in: query description: > The subsection permissions to return the ancillary permissions for. These values are comma seperated. Ex. subsection_permissions=sysconsole_read_reporting_site_statistics,sysconsole_write_reporting_site_statistics,sysconsole_write_user_management_channels schema: type: string responses: "200": description: Successfully returned all ancillary and requested permissions content: application/json: schema: type: array items: type: string "400": $ref: '#/components/responses/BadRequest' /api/v4/imports: get: tags: - imports summary: List import files description: > Lists all available import files. __Minimum server version__: 5.31 ##### Permissions Must have `manage_system` permissions. operationId: ListImports responses: "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' /api/v4/exports: get: tags: - exports summary: List export files description: > Lists all available export files. __Minimum server version__: 5.33 ##### Permissions Must have `manage_system` permissions. operationId: ListExports responses: "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "500": $ref: '#/components/responses/InternalServerError' /api/v4/exports/{export_name}: get: tags: - exports summary: Download an export file description: | Downloads an export file. __Minimum server version__: 5.33 ##### Permissions Must have `manage_system` permissions. operationId: DownloadExport parameters: - name: export_name in: path description: The name of the export file to download required: true schema: type: string responses: "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' delete: tags: - exports summary: Delete an export file description: | Deletes an export file. __Minimum server version__: 5.33 ##### Permissions Must have `manage_system` permissions. operationId: DeleteExport parameters: - name: export_name in: path description: The name of the export file to delete required: true schema: type: string responses: "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "500": $ref: '#/components/responses/InternalServerError' /api/v4/ip_filtering: get: tags: - ip - filtering summary: Get all IP filters description: > Retrieve a list of IP filters applied to the workspace __Minimum server version__: 9.1 __Note:__ This is intended for internal use and only applicable to Cloud workspaces operationId: GetIPFilters responses: "200": description: IP Filters returned successfully content: application/json: schema: type: array items: $ref: '#/components/schemas/AllowedIPRange' "401": $ref: '#/components/responses/Unauthorized' "500": $ref: '#/components/responses/InternalServerError' "501": $ref: '#/components/responses/NotImplemented' post: tags: - ip - filtering summary: Get all IP filters description: > Adjust IP Filters applied to the workspace __Minimum server version__: 9.1 __Note:__ This is intended for internal use and only applicable to Cloud workspaces operationId: ApplyIPFilters requestBody: content: application/json: schema: type: array items: $ref: '#/components/schemas/AllowedIPRange' description: IP Filters to apply required: true responses: "200": description: IP Filters returned successfully content: application/json: schema: type: array items: $ref: '#/components/schemas/AllowedIPRange' "401": $ref: '#/components/responses/Unauthorized' "500": $ref: '#/components/responses/InternalServerError' "501": $ref: '#/components/responses/NotImplemented' /api/v4/ip_filtering/my_ip: get: tags: - ip - filtering summary: Get all IP filters description: > Retrieve your current IP address as seen by the workspace __Minimum server version__: 9.1 __Note:__ This is intended for internal use and only applicable to Cloud workspaces operationId: MyIP responses: "200": description: IP address returned successfully content: application/json: schema: type: object properties: ip: type: string description: Your current IP address example: "192.168.0.1" "401": $ref: '#/components/responses/Unauthorized' "500": $ref: '#/components/responses/InternalServerError' "501": $ref: '#/components/responses/NotImplemented' /api/v4/channels/{channel_id}/bookmarks: get: tags: - bookmarks summary: Get channel bookmarks for Channel description: | __Minimum server version__: 9.5 operationId: ListChannelBookmarksForChannel parameters: - name: channel_id in: path description: Channel GUID required: true schema: type: string - name: bookmarks_since in: query description: | Timestamp to filter the bookmarks with. If set, the endpoint returns bookmarks that have been added, updated or deleted since its value schema: type: number format: int64 responses: "201": description: Channel Bookmarks retrieval successful content: application/json: schema: type: array items: $ref: '#/components/schemas/ChannelBookmarkWithFileInfo' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' post: tags: - bookmarks summary: Create channel bookmark description: | Creates a new channel bookmark for this channel. __Minimum server version__: 9.5 ##### Permissions Must have the `add_bookmark_public_channel` or `add_bookmark_private_channel` depending on the channel type. If the channel is a DM or GM, must be a non-guest member. operationId: CreateChannelBookmark parameters: - name: channel_id in: path description: Channel GUID required: true schema: type: string requestBody: content: application/json: schema: type: object required: - display_name - type properties: file_id: type: string description: The ID of the file associated with the channel bookmark. Required for bookmarks of type 'file' display_name: type: string description: The name of the channel bookmark link_url: type: string description: The URL associated with the channel bookmark. Required for bookmarks of type 'link' image_url: type: string description: The URL of the image associated with the channel bookmark. Optional, only applies for bookmarks of type 'link' emoji: type: string description: The emoji of the channel bookmark type: type: string enum: - link - file description: | * `link` for channel bookmarks that reference a link. `link_url` is requied * `file` for channel bookmarks that reference a file. `file_id` is required description: Channel Bookmark object to be created required: true responses: "201": description: Channel Bookmark creation successful content: application/json: schema: $ref: '#/components/schemas/ChannelBookmarkWithFileInfo' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' /api/v4/channels/{channel_id}/bookmarks/{bookmark_id}: patch: tags: - bookmarks summary: Update channel bookmark description: | Partially update a channel bookmark by providing only the fields you want to update. Ommited fields will not be updated. The fields that can be updated are defined in the request body, all other provided fields will be ignored. __Minimum server version__: 9.5 ##### Permissions Must have the `edit_bookmark_public_channel` or `edit_bookmark_private_channel` depending on the channel type. If the channel is a DM or GM, must be a non-guest member. operationId: UpdateChannelBookmark parameters: - name: channel_id in: path description: Channel GUID required: true schema: type: string - name: bookmark_id in: path description: Bookmark GUID required: true schema: type: string requestBody: content: application/json: schema: type: object properties: file_id: type: string description: The ID of the file associated with the channel bookmark. Required for bookmarks of type 'file' display_name: type: string description: The name of the channel bookmark sort_order: type: integer format: int64 description: The order of the channel bookmark link_url: type: string description: The URL associated with the channel bookmark. Required for type bookmarks of type 'link' image_url: type: string description: The URL of the image associated with the channel bookmark emoji: type: string description: The emoji of the channel bookmark type: type: string enum: - link - file description: | * `link` for channel bookmarks that reference a link. `link_url` is requied * `file` for channel bookmarks that reference a file. `file_id` is required description: Channel Bookmark object to be updated required: true responses: "200": description: Channel Bookmark update successful content: application/json: schema: $ref: '#/components/schemas/UpdateChannelBookmarkResponse' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFound' delete: tags: - bookmarks summary: Delete channel bookmark description: | Archives a channel bookmark. This will set the `deleteAt` to the current timestamp in the database. __Minimum server version__: 9.5 ##### Permissions Must have the `delete_bookmark_public_channel` or `delete_bookmark_private_channel` depending on the channel type. If the channel is a DM or GM, must be a non-guest member. operationId: DeleteChannelBookmark parameters: - name: channel_id in: path description: Channel GUID required: true schema: type: string - name: bookmark_id in: path description: Bookmark GUID required: true schema: type: string responses: "200": description: Channel Bookmark deletion successful content: application/json: schema: $ref: '#/components/schemas/ChannelBookmarkWithFileInfo' "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}/bookmarks/{bookmark_id}/sort_order: post: tags: - bookmarks summary: Update channel bookmark's order description: | Updates the order of a channel bookmark, setting its new order from the parameters and updating the rest of the bookmarks of the channel to accomodate for this change. __Minimum server version__: 9.5 ##### Permissions Must have the `order_bookmark_public_channel` or `order_bookmark_private_channel` depending on the channel type. If the channel is a DM or GM, must be a non-guest member. operationId: UpdateChannelBookmarkSortOrder parameters: - name: channel_id in: path description: Channel GUID required: true schema: type: string - name: bookmark_id in: path description: Bookmark GUID required: true schema: type: string requestBody: content: application/json: schema: type: number format: int64 description: The new sort order for the Channel Bookmark responses: "200": description: Channel Bookmark Sort Order update successful content: application/json: schema: type: array items: $ref: '#/components/schemas/ChannelBookmarkWithFileInfo' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' /api/v4/reports/users: get: tags: - users summary: Get a list of paged and sorted users for admin reporting purposes description: > Get a list of paged users for admin reporting purposes, based on provided parameters. Must be a system admin to invoke this API. ##### Permissions Requires `sysconsole_read_user_management_users`. operationId: GetUsersForReporting parameters: - name: sort_column in: query description: The column to sort the users by. Must be one of ("CreateAt", "Username", "FirstName", "LastName", "Nickname", "Email") or the API will return an error. schema: type: string default: 'Username' - name: direction in: query description: The direction in which to accept paging values from. Will return values ahead of the cursor if "up", and below the cursor if "down". Default is "down". schema: type: string default: 'down' - name: sort_direction in: query description: The sorting direction. Must be one of ("asc", "desc"). Will default to 'asc' if not specified or the input is invalid. schema: type: string default: 'asc' - name: page_size in: query description: The maximum number of users to return. schema: type: integer default: 50 minimum: !!float 1 maximum: !!float 100 - name: from_column_value in: query description: The value of the sorted column corresponding to the cursor to read from. Should be blank for the first page asked for. schema: type: string - name: from_id in: query description: The value of the user id corresponding to the cursor to read from. Should be blank for the first page asked for. schema: type: string - name: date_range in: query description: The date range of the post statistics to display. Must be one of ("last30days", "previousmonth", "last6months", "alltime"). Will default to 'alltime' if the input is not valid. schema: type: string default: 'alltime' - name: role_filter in: query description: Filter users by their role. schema: type: string - name: team_filter in: query description: Filter users by a specified team ID. schema: type: string - name: has_no_team in: query description: If true, show only users that have no team. Will ignore provided "team_filter" if true. schema: type: boolean - name: hide_active in: query description: If true, show only users that are inactive. Cannot be used at the same time as "hide_inactive" schema: type: boolean - name: hide_inactive in: query description: If true, show only users that are active. Cannot be used at the same time as "hide_active" schema: type: boolean - name: search_term in: query description: A filtering search term that allows filtering by Username, FirstName, LastName, Nickname or Email schema: type: string responses: "200": description: User page retrieval successful content: application/json: schema: type: array items: $ref: '#/components/schemas/UserReport' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "500": $ref: '#/components/responses/InternalServerError' /api/v4/reports/users/count: get: tags: - users summary: Gets the full count of users that match the filter. description: > Get the full count of users admin reporting purposes, based on provided parameters. Must be a system admin to invoke this API. ##### Permissions Requires `sysconsole_read_user_management_users`. operationId: GetUserCountForReporting parameters: - name: role_filter in: query description: Filter users by their role. schema: type: string - name: team_filter in: query description: Filter users by a specified team ID. schema: type: string - name: has_no_team in: query description: If true, show only users that have no team. Will ignore provided "team_filter" if true. schema: type: boolean - name: hide_active in: query description: If true, show only users that are inactive. Cannot be used at the same time as "hide_inactive" schema: type: boolean - name: hide_inactive in: query description: If true, show only users that are active. Cannot be used at the same time as "hide_active" schema: type: boolean - name: search_term in: query description: A filtering search term that allows filtering by Username, FirstName, LastName, Nickname or Email schema: type: string responses: "200": description: User count retrieval successful content: application/json: schema: type: number /api/v4/reports/users/export: post: tags: - reports summary: Starts a job to export the users to a report file. description: > Starts a job to export the users to a report file. Must be a system admin to invoke this API. ##### Permissions Requires `sysconsole_read_user_management_users`. operationId: StartBatchUsersExport parameters: - name: date_range in: query description: The date range of the post statistics to display. Must be one of ("last30days", "previousmonth", "last6months", "alltime"). Will default to 'alltime' if the input is not valid. schema: type: string default: 'alltime' responses: "200": description: Job successfully started content: application/json: schema: type: array items: $ref: '#/components/schemas/UserReport' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "500": $ref: '#/components/responses/InternalServerError' /api/v4/limits/users: get: tags: - users summary: Gets the user limits for the server description: > Gets the user limits for the server ##### Permissions Requires `sysconsole_read_user_management_users`. operationId: getUserLimits responses: "200": description: User limits for server content: application/json: schema: type: array items: $ref: '#/components/schemas/UserLimits' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "500": $ref: '#/components/responses/InternalServerError' /api/v4/oauth/outgoing_connections: get: tags: - oauth - outgoing_connections - outgoing_oauth_connections summary: List all connections description: > List all outgoing OAuth connections. __Minimum server version__: 9.6 operationId: ListOutgoingOAuthConnections parameters: - name: team_id in: query description: Current Team ID in integrations backstage required: true schema: type: string responses: "200": description: Successfully fetched outgoing OAuth connections content: application/json: schema: type: array items: $ref: '#/components/schemas/OutgoingOAuthConnectionGetItem' "401": $ref: '#/components/responses/Unauthorized' "500": $ref: '#/components/responses/InternalServerError' "501": $ref: '#/components/responses/NotImplemented' post: tags: - oauth - outgoing_connections - outgoing_oauth_connections summary: Create a connection description: > Create an outgoing OAuth connection. __Minimum server version__: 9.6 operationId: CreateOutgoingOAuthConnection parameters: - name: team_id in: query description: Current Team ID in integrations backstage required: true schema: type: string requestBody: description: Outgoing OAuth connection to create content: application/json: schema: $ref: '#/components/schemas/OutgoingOAuthConnectionPostItem' responses: "201": description: Successfully created outgoing OAuth connection content: application/json: schema: $ref: '#/components/schemas/OutgoingOAuthConnectionGetItem' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "500": $ref: '#/components/responses/InternalServerError' "501": $ref: '#/components/responses/NotImplemented' /api/v4/oauth/outgoing_connections/{connection_id}: get: tags: - oauth - outgoing_connections - outgoing_oauth_connections summary: Get a connection description: > Retrieve an outgoing OAuth connection. __Minimum server version__: 9.6 operationId: GetOutgoingOAuthConnection parameters: - name: team_id in: query description: Current Team ID in integrations backstage required: true schema: type: string responses: "200": description: Successfully fetched outgoing OAuth connection content: application/json: schema: $ref: '#/components/schemas/OutgoingOAuthConnectionGetItem' "401": $ref: '#/components/responses/Unauthorized' "500": $ref: '#/components/responses/InternalServerError' "501": $ref: '#/components/responses/NotImplemented' put: tags: - oauth - outgoing_connections - outgoing_oauth_connections summary: Update a connection description: > Update an outgoing OAuth connection. __Minimum server version__: 9.6 operationId: UpdateOutgoingOAuthConnection parameters: - name: team_id in: query description: Current Team ID in integrations backstage required: true schema: type: string requestBody: description: Outgoing OAuth connection to update content: application/json: schema: $ref: '#/components/schemas/OutgoingOAuthConnectionPostItem' responses: "200": description: Successfully updated outgoing OAuth connection content: application/json: schema: $ref: '#/components/schemas/OutgoingOAuthConnectionGetItem' "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' "501": $ref: '#/components/responses/NotImplemented' delete: tags: - oauth - outgoing_connections - outgoing_oauth_connections summary: Delete a connection description: > Delete an outgoing OAuth connection. __Minimum server version__: 9.6 operationId: DeleteOutgoingOAuthConnection parameters: - name: team_id in: query description: Current Team ID in integrations backstage required: true schema: type: string responses: "200": description: Successfully deleted outgoing OAuth connection "401": $ref: '#/components/responses/Unauthorized' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' "501": $ref: '#/components/responses/NotImplemented' /api/v4/oauth/outgoing_connections/validate: post: tags: - oauth - outgoing_connections - outgoing_oauth_connections summary: Validate a connection configuration description: > Validate an outgoing OAuth connection. If an id is provided in the payload, and no client secret is provided, then the stored client secret is implicitly used for the validation. __Minimum server version__: 9.6 operationId: ValidateOutgoingOAuthConnection parameters: - name: team_id in: query description: Current Team ID in integrations backstage required: true schema: type: string requestBody: description: Outgoing OAuth connection to validate content: application/json: schema: $ref: '#/components/schemas/OutgoingOAuthConnectionPostItem' responses: "200": description: The connection configuration is valid. "400": $ref: '#/components/responses/BadRequest' "401": $ref: '#/components/responses/Unauthorized' "404": $ref: '#/components/responses/NotFound' "500": $ref: '#/components/responses/InternalServerError' "501": $ref: '#/components/responses/NotImplemented' "502": $ref: '#/components/responses/BadGateway' /plugins/playbooks/api/v0/runs: get: summary: List all playbook runs description: Retrieve a paged list of playbook runs, filtered by team, status, owner, name and/or members, and sorted by ID, name, status, creation date, end date, team or owner ID. operationId: listPlaybookRuns security: - BearerAuth: [] tags: - PlaybookRuns parameters: - name: team_id in: query description: ID of the team to filter by. required: true example: el3d3t9p55pevvxs2qkdwz334k schema: type: string - name: page in: query description: Zero-based index of the page to request. example: "3" schema: type: integer format: int32 default: 0 - name: per_page in: query description: Number of playbook runs to return per page. example: "50" schema: type: integer format: int32 default: 1000 - name: sort in: query description: Field to sort the returned playbook runs by. example: end_at schema: type: string default: create_at enum: - id - name - is_active - create_at - end_at - team_id - owner_user_id - name: direction in: query description: Direction (ascending or descending) followed by the sorting of the playbook runs. example: asc schema: type: string default: desc enum: - desc - asc - name: statuses in: query description: The returned list will contain only the playbook runs with the specified statuses. example: InProgress schema: type: array default: - InProgress items: type: string enum: - InProgress - Finished style: form explode: true - name: owner_user_id in: query description: The returned list will contain only the playbook runs commanded by this user. Specify "me" for current user. example: lpn2ogt9qzkc59lfvvad9t15v4 schema: type: string - name: participant_id in: query description: The returned list will contain only the playbook runs for which the given user is a participant. Specify "me" for current user. example: bruhg1cs65retdbea798hrml4v schema: type: string - name: search_term in: query description: The returned list will contain only the playbook runs whose name contains the search term. example: server down schema: type: string x-codeSamples: - lang: curl source: | curl -X GET 'http://localhost:8065/plugins/playbooks/api/v0/runs' \ -H 'Authorization: Bearer 9g64ig7q9pds8yjz8rsgd6e36e' responses: "200": description: A paged list of playbook runs. content: application/json: schema: $ref: '#/components/schemas/PlaybookRunList' "400": $ref: '#/components/responses/400' "403": $ref: '#/components/responses/403' "500": $ref: '#/components/responses/500' post: summary: Create a new playbook run description: Create a new playbook run in a team, using a playbook as template, with a specific name and a specific owner. operationId: createPlaybookRunFromPost security: - BearerAuth: [] tags: - PlaybookRuns requestBody: description: Playbook run payload. content: application/json: schema: type: object required: - name - owner_user_id - team_id - playbook_id properties: name: type: string description: The name of the playbook run. example: Server down in EU cluster description: type: string description: The description of the playbook run. example: There is one server in the EU cluster that is not responding since April 12. owner_user_id: type: string description: The identifier of the user who is commanding the playbook run. example: bqnbdf8uc0a8yz4i39qrpgkvtg team_id: type: string description: The identifier of the team where the playbook run's channel is in. example: 61ji2mpflefup3cnuif80r5rde post_id: type: string description: If the playbook run was created from a post, this field contains the identifier of such post. If not, this field is empty. example: b2ntfcrl4ujivl456ab4b3aago playbook_id: type: string description: The identifier of the playbook with from which this playbook run was created. example: 0y4a0ntte97cxvfont8y84wa7x x-codeSamples: - lang: curl source: | curl -X POST 'http://localhost:8065/plugins/playbooks/api/v0/runs' \ -H 'Authorization: Bearer 9g64ig7q9pds8yjz8rsgd6e36e'\ -H 'Content-Type: application/json'\ -d '{"name": "Server down in EU cluster", "description": "There is one server in the EU cluster that is not responding since April 12.", "owner_user_id": "bqnbdf8uc0a8yz4i39qrpgkvtg", "team_id": "61ji2mpflefup3cnuif80r5rde", "playbook_id": "0y4a0ntte97cxvfont8y84wa7x"}' responses: "201": description: Created playbook run. headers: Location: description: Location of the created playbook run. schema: type: string example: /api/v0/runs/nhkx1nbivu45lr84vtxxukp2vr example: /api/v0/runs/nhkx1nbivu45lr84vtxxukp2vr content: application/json: schema: $ref: '#/components/schemas/PlaybookRun' "400": $ref: '#/components/responses/400' "403": $ref: '#/components/responses/403' "500": $ref: '#/components/responses/500' /plugins/playbooks/api/v0/runs/dialog: post: summary: Create a new playbook run from dialog description: This is an internal endpoint to create a playbook run from the submission of an interactive dialog, filled by a user in the webapp. See [Interactive Dialogs](https://docs.mattermost.com/developer/interactive-dialogs.html) for more information. operationId: createPlaybookRunFromDialog security: - BearerAuth: [] tags: - Internal requestBody: description: Dialog submission payload. content: application/json: schema: type: object properties: type: type: string example: dialog_submission url: type: string callback_id: type: string description: Callback ID provided by the integration. state: type: string description: Stringified JSON with the post_id and the client_id. user_id: type: string description: ID of the user who submitted the dialog. channel_id: type: string description: ID of the channel the user was in when submitting the dialog. team_id: type: string description: ID of the team the user was on when submitting the dialog. submission: type: object description: Map of the dialog fields to their values required: - playbookID - playbookRunName properties: playbookID: type: string description: ID of the playbook to create the playbook run from. example: ahz0s61gh275i7z2ag4g1ntvjm playbookRunName: type: string description: The name of the playbook run to be created. example: Server down in EU cluster. playbookRunDescription: type: string description: An optional description of the playbook run. example: There is one server in the EU cluster that is not responding since April 12. cancelled: type: boolean description: If the dialog was cancelled. responses: "201": description: Created playbook run. headers: Location: description: Location of the created playbook run. schema: type: string example: /api/v0/runs/nhkx1nbivu45lr84vtxxukp2vr example: /api/v0/runs/nhkx1nbivu45lr84vtxxukp2vr content: application/json: schema: $ref: '#/components/schemas/PlaybookRun' "400": $ref: '#/components/responses/400' "403": $ref: '#/components/responses/403' "500": $ref: '#/components/responses/500' /plugins/playbooks/api/v0/runs/owners: get: summary: Get all owners description: Get the owners of all playbook runs, filtered by team. operationId: getOwners security: - BearerAuth: [] tags: - PlaybookRuns parameters: - name: team_id in: query description: ID of the team to filter by. required: true example: el3d3t9p55pevvxs2qkdwz334k schema: type: string x-codeSamples: - lang: curl source: | curl -X GET 'http://localhost:8065/plugins/playbooks/api/v0/runs/owners?team_id=ni8duypfe7bamprxqeffd563gy' \ -H 'Authorization: Bearer 9g64ig7q9pds8yjz8rsgd6e36e' responses: "200": description: A list of owners. content: application/json: schema: type: array items: $ref: '#/components/schemas/OwnerInfo' "400": $ref: '#/components/responses/400' "403": $ref: '#/components/responses/403' "500": $ref: '#/components/responses/500' /plugins/playbooks/api/v0/runs/channels: get: summary: Get playbook run channels description: Get all channels associated with a playbook run, filtered by team, status, owner, name and/or members, and sorted by ID, name, status, creation date, end date, team, or owner ID. operationId: getChannels security: - BearerAuth: [] tags: - PlaybookRuns parameters: - name: team_id in: query description: ID of the team to filter by. required: true example: el3d3t9p55pevvxs2qkdwz334k schema: type: string - name: sort in: query description: Field to sort the returned channels by, according to their playbook run. example: end_at schema: type: string default: create_at enum: - id - name - create_at - end_at - team_id - owner_user_id - name: direction in: query description: Direction (ascending or descending) followed by the sorting of the playbook runs associated to the channels. example: asc schema: type: string default: desc enum: - desc - asc - name: status in: query description: The returned list will contain only the channels whose playbook run has this status. example: active schema: type: string default: all enum: - all - InProgress - Finished - name: owner_user_id in: query description: The returned list will contain only the channels whose playbook run is commanded by this user. example: lpn2ogt9qzkc59lfvvad9t15v4 schema: type: string - name: search_term in: query description: The returned list will contain only the channels associated to a playbook run whose name contains the search term. example: server down schema: type: string - name: participant_id in: query description: The returned list will contain only the channels associated to a playbook run for which the given user is a participant. example: bruhg1cs65retdbea798hrml4v schema: type: string x-codeSamples: - lang: curl source: | curl -X GET 'http://localhost:8065/plugins/playbooks/api/v0/runs/channels?team_id=ni8duypfe7bamprxqeffd563gy' \ -H 'Authorization: Bearer 9g64ig7q9pds8yjz8rsgd6e36e' responses: "200": description: Channel IDs. content: application/json: schema: type: array items: type: string description: ID of the channel. example: v8zdc1893plelmf54vb7f0ramn example: v8zdc1893plelmf54vb7f0ramn "400": $ref: '#/components/responses/400' "403": $ref: '#/components/responses/403' "500": $ref: '#/components/responses/500' /plugins/playbooks/api/v0/runs/checklist-autocomplete: get: summary: Get autocomplete data for /playbook check description: This is an internal endpoint used by the autocomplete system to retrieve the data needed to show the list of items that the user can check. operationId: getChecklistAutocomplete security: - BearerAuth: [] tags: - Internal parameters: - name: channel_ID in: query description: ID of the channel the user is in. required: true example: r3vk8jdys4rlya46xhdthatoyx schema: type: string responses: "200": description: List of autocomplete items for this channel. content: application/json: schema: type: array items: type: object required: - item - hint - helptext properties: item: type: string description: A string containing a pair of integers separated by a space. The first integer is the index of the checklist; the second is the index of the item within the checklist. example: 1 2 hint: type: string description: The title of the corresponding item. example: Gather information from customer. helptext: type: string description: Always the value "Check/uncheck this item". example: Check/uncheck this item "500": $ref: '#/components/responses/500' /plugins/playbooks/api/v0/runs/channel/{channel_id}: get: summary: Find playbook run by channel ID operationId: getPlaybookRunByChannelId security: - BearerAuth: [] tags: - PlaybookRuns parameters: - name: channel_id in: path required: true description: ID of the channel associated to the playbook run to retrieve. schema: type: string example: hwrmiyzj3kadcilh3ukfcnsbt6 example: hwrmiyzj3kadcilh3ukfcnsbt6 x-codeSamples: - lang: curl source: | curl -X GET 'http://localhost:8065/plugins/playbooks/api/v0/runs/channel/hwrmiyzj3kadcilh3ukfcnsbt6' \ -H 'Authorization: Bearer 9g64ig7q9pds8yjz8rsgd6e36e' responses: "200": description: Playbook run associated to the channel. content: application/json: schema: $ref: '#/components/schemas/PlaybookRun' "404": $ref: '#/components/responses/404' "500": $ref: '#/components/responses/500' /plugins/playbooks/api/v0/runs/{id}: get: summary: Get a playbook run operationId: getPlaybookRun security: - BearerAuth: [] tags: - PlaybookRuns parameters: - name: id in: path required: true description: ID of the playbook run to retrieve. schema: type: string example: mx3xyzdojfgyfdx8sc8of1gdme example: mx3xyzdojfgyfdx8sc8of1gdme x-codeSamples: - lang: curl source: | curl -X GET 'http://localhost:8065/plugins/playbooks/api/v0/runs/mx3xyzdojfgyfdx8sc8of1gdme' \ -H 'Authorization: Bearer 9g64ig7q9pds8yjz8rsgd6e36e' responses: "200": description: Playbook run content: application/json: schema: $ref: '#/components/schemas/PlaybookRun' "403": $ref: '#/components/responses/403' "500": $ref: '#/components/responses/500' patch: summary: Update a playbook run operationId: updatePlaybookRun security: - BearerAuth: [] tags: - PlaybookRuns parameters: - name: id in: path required: true description: ID of the playbook run to retrieve. schema: type: string example: mx3xyzdojfgyfdx8sc8of1gdme example: mx3xyzdojfgyfdx8sc8of1gdme requestBody: description: Playbook run update payload. content: application/json: schema: type: object properties: active_stage: type: integer description: Zero-based index of the stage that will be made active. example: 2 x-codeSamples: - lang: curl source: | curl -X PATCH 'http://localhost:8065/plugins/playbooks/api/v0/runs/mx3xyzdojfgyfdx8sc8of1gdme' \ -H 'Authorization: Bearer 9g64ig7q9pds8yjz8rsgd6e36e'\ -H 'Content-Type: application/json'\ -d '{"active_stage": 2}' responses: "200": description: Playbook run successfully updated. "400": $ref: '#/components/responses/400' "500": $ref: '#/components/responses/500' /plugins/playbooks/api/v0/runs/{id}/metadata: get: summary: Get playbook run metadata operationId: getPlaybookRunMetadata security: - BearerAuth: [] tags: - PlaybookRuns parameters: - name: id in: path required: true description: ID of the playbook run whose metadata will be retrieved. schema: type: string example: mx3xyzdojfgyfdx8sc8of1gdme example: mx3xyzdojfgyfdx8sc8of1gdme x-codeSamples: - lang: curl source: | curl -X GET 'http://localhost:8065/plugins/playbooks/api/v0/runs/1igmynxs77ywmcbwbsujzktter/details' \ -H 'Authorization: Bearer 9g64ig7q9pds8yjz8rsgd6e36e' responses: "200": description: Playbook run metadata. content: application/json: schema: $ref: '#/components/schemas/PlaybookRunMetadata' "403": $ref: '#/components/responses/403' "500": $ref: '#/components/responses/500' /plugins/playbooks/api/v0/runs/{id}/end: put: summary: End a playbook run operationId: endPlaybookRun security: - BearerAuth: [] tags: - PlaybookRuns parameters: - name: id in: path required: true description: ID of the playbook run to end. schema: type: string example: 1igmynxs77ywmcbwbsujzktter example: 1igmynxs77ywmcbwbsujzktter x-codeSamples: - lang: curl source: | curl -X PUT 'http://localhost:8065/plugins/playbooks/api/v0/runs/1igmynxs77ywmcbwbsujzktter/end' \ -H 'Authorization: Bearer 9g64ig7q9pds8yjz8rsgd6e36e' responses: "200": description: Playbook run ended "500": $ref: '#/components/responses/500' post: summary: End a playbook run from dialog description: This is an internal endpoint to end a playbook run via a confirmation dialog, submitted by a user in the webapp. operationId: endPlaybookRunDialog security: - BearerAuth: [] tags: - Internal parameters: - name: id in: path required: true description: ID of the playbook run to end. schema: type: string example: 1igmynxs77ywmcbwbsujzktter example: 1igmynxs77ywmcbwbsujzktter x-codeSamples: - lang: curl source: | curl -X POST 'http://localhost:8065/plugins/playbooks/api/v0/runs/1igmynxs77ywmcbwbsujzktter/end' \ -H 'Authorization: Bearer 9g64ig7q9pds8yjz8rsgd6e36e' responses: "200": description: Playbook run ended "500": $ref: '#/components/responses/500' /plugins/playbooks/api/v0/runs/{id}/restart: put: summary: Restart a playbook run operationId: restartPlaybookRun security: - BearerAuth: [] tags: - PlaybookRuns parameters: - name: id in: path required: true description: ID of the playbook run to restart. schema: type: string example: 1igmynxs77ywmcbwbsujzktter example: 1igmynxs77ywmcbwbsujzktter x-codeSamples: - lang: curl source: | curl -X PUT 'http://localhost:8065/plugins/playbooks/api/v0/runs/1igmynxs77ywmcbwbsujzktter/end' \ -H 'Authorization: Bearer 9g64ig7q9pds8yjz8rsgd6e36e' responses: "200": description: Playbook run restarted. "500": $ref: '#/components/responses/500' /plugins/playbooks/api/v0/runs/{id}/status: post: summary: Update a playbook run's status operationId: status security: - BearerAuth: [] tags: - PlaybookRuns parameters: - name: id in: path required: true description: ID of the playbook run to update. schema: type: string example: 1igmynxs77ywmcbwbsujzktter example: 1igmynxs77ywmcbwbsujzktter requestBody: description: Payload to change the playbook run's status update message. content: application/json: schema: type: object properties: message: type: string description: The status update message. example: Starting to investigate. reminder: type: number description: The number of seconds until the system will send a reminder to the owner to update the status. No reminder will be scheduled if reminder is 0 or omitted. example: 600 required: - description - message x-codeSamples: - lang: curl source: | curl -X PUT 'http://localhost:8065/plugins/playbooks/api/v0/runs/1igmynxs77ywmcbwbsujzktter/update-status' \ -H 'Authorization: Bearer 9g64ig7q9pds8yjz8rsgd6e36e' -d '{"message": "Finishing playbook run because the issue was solved."}' responses: "200": description: Playbook run updated. "400": $ref: '#/components/responses/400' "403": $ref: '#/components/responses/403' "500": $ref: '#/components/responses/500' /plugins/playbooks/api/v0/runs/{id}/finish: put: summary: Finish a playbook operationId: finish security: - BearerAuth: [] tags: - PlaybookRuns parameters: - name: id in: path required: true description: ID of the playbook run to finish. schema: type: string example: 1igmynxs77ywmcbwbsujzktter example: 1igmynxs77ywmcbwbsujzktter x-codeSamples: - lang: curl source: | curl -X PUT 'http://localhost:8065/plugins/playbooks/api/v0/runs/1igmynxs77ywmcbwbsujzktter/finish' \ -H 'Authorization: Bearer 9g64ig7q9pds8yjz8rsgd6e36e' responses: "200": description: Playbook run finished. "500": $ref: '#/components/responses/500' /plugins/playbooks/api/v0/runs/{id}/owner: post: summary: Update playbook run owner operationId: changeOwner security: - BearerAuth: [] tags: - PlaybookRuns parameters: - name: id in: path required: true description: ID of the playbook run whose owner will be changed. schema: type: string example: 1igmynxs77ywmcbwbsujzktter example: 1igmynxs77ywmcbwbsujzktter requestBody: description: Payload to change the playbook run's owner. content: application/json: schema: type: object properties: owner_id: type: string description: The user ID of the new owner. example: hx7fqtqxp7nn8129t7e505ls6s required: - owner_id x-codeSamples: - lang: curl source: | curl -X POST 'http://localhost:8065/plugins/playbooks/api/v0/runs/1igmynxs77ywmcbwbsujzktter/owner' \ -H 'Authorization: Bearer 9g64ig7q9pds8yjz8rsgd6e36e'\ -d '{"owner_id": "hx7fqtqxp7nn8129t7e505ls6s"}' responses: "200": description: Owner successfully changed. "400": $ref: '#/components/responses/400' "403": $ref: '#/components/responses/403' "500": $ref: '#/components/responses/500' /plugins/playbooks/api/v0/runs/{id}/next-stage-dialog: post: summary: Go to next stage from dialog description: This is an internal endpoint to go to the next stage via a confirmation dialog, submitted by a user in the webapp. operationId: nextStageDialog security: - BearerAuth: [] tags: - Internal parameters: - in: path name: id schema: type: string required: true description: The PlaybookRun ID requestBody: description: Dialog submission payload. content: application/json: schema: type: object properties: state: type: string description: String representation of the zero-based index of the stage to go to. example: "3" responses: "200": description: Playbook run stage update. "400": $ref: '#/components/responses/400' "500": $ref: '#/components/responses/500' /plugins/playbooks/api/v0/runs/{id}/checklists/{checklist}/add: post: summary: Add an item to a playbook run's checklist description: The most common pattern to add a new item is to only send its title as the request payload. By default, it is an open item, with no assignee and no slash command. operationId: addChecklistItem security: - BearerAuth: [] tags: - PlaybookRuns parameters: - name: id in: path required: true description: ID of the playbook run whose checklist will be modified. example: twcqg0a2m37ydi6ebge3j9ev5z schema: type: string - name: checklist in: path required: true description: Zero-based index of the checklist to modify. example: "1" schema: type: integer requestBody: description: Checklist item payload. content: application/json: schema: type: object required: - title properties: title: type: string description: The title of the checklist item. example: Gather information from customer. state: type: string enum: - "" - in_progress - closed description: The state of the checklist item. An empty string means that the item is not done. example: closed state_modified: type: integer format: int64 description: The timestamp for the latest modification of the item's state, formatted as the number of milliseconds since the Unix epoch. It equals 0 if the item was never modified. example: 1607774621321 assignee_id: type: string description: The identifier of the user that has been assigned to complete this item. If the item has no assignee, this is an empty string. example: pisdatkjtdlkdhht2v4inxuzx1 assignee_modified: type: integer format: int64 description: The timestamp for the latest modification of the item's assignee, formatted as the number of milliseconds since the Unix epoch. It equals 0 if the item never got an assignee. example: 1608897821125 command: type: string description: The slash command associated with this item. If the item has no slash command associated, this is an empty string example: /opsgenie on-call command_last_run: type: integer format: int64 description: The timestamp for the latest execution of the item's command, formatted as the number of milliseconds since the Unix epoch. It equals 0 if the command was never executed. example: 1608552221019 description: type: string description: A detailed description of the checklist item, formatted with Markdown. example: Ask the customer for more information in [Zendesk](https://www.zendesk.com/). x-codeSamples: - lang: curl source: | curl -X PUT 'http://localhost:8065/plugins/playbooks/api/v0/runs/twcqg0a2m37ydi6ebge3j9ev5z/checklists/1/add' \ -H 'Authorization: Bearer 9g64ig7q9pds8yjz8rsgd6e36e'\ -d '{"title": "Gather information from customer."}' responses: default: description: Error response content: application/json: schema: $ref: '#/components/schemas/Error' "200": description: Item successfully added. /plugins/playbooks/api/v0/runs/{id}/checklists/{checklist}/reorder: put: summary: Reorder an item in a playbook run's checklist operationId: reoderChecklistItem security: - BearerAuth: [] tags: - PlaybookRuns parameters: - name: id in: path required: true description: ID of the playbook run whose checklist will be modified. example: yj74zsk7dvtsv6ndsynsps3g5s schema: type: string - name: checklist in: path required: true description: Zero-based index of the checklist to modify. example: "1" schema: type: integer requestBody: description: Reorder checklist item payload. content: application/json: schema: type: object properties: item_num: type: integer description: Zero-based index of the item to reorder. example: 2 new_location: type: integer description: Zero-based index of the new place to move the item to. example: 2 required: - item_num - new_location x-codeSamples: - lang: curl source: | curl -X PUT 'http://localhost:8065/plugins/playbooks/api/v0/runs/yj74zsk7dvtsv6ndsynsps3g5s/checklists/1/reorder' \ -H 'Authorization: Bearer 9g64ig7q9pds8yjz8rsgd6e36e'\ -d '{"item_num": 0, "new_location": 2}' responses: "200": description: Item successfully reordered. "400": $ref: '#/components/responses/400' "500": $ref: '#/components/responses/500' /plugins/playbooks/api/v0/runs/{id}/checklists/{checklist}/item/{item}: put: summary: Update an item of a playbook run's checklist description: Update the title and the slash command of an item in one of the playbook run's checklists. operationId: itemRename security: - BearerAuth: [] tags: - PlaybookRuns parameters: - name: id in: path required: true description: ID of the playbook run whose checklist will be modified. example: 6t7jdgyqr7b5sk24zkauhmrb06 schema: type: string - name: checklist in: path required: true description: Zero-based index of the checklist to modify. example: "1" schema: type: integer - name: item in: path required: true description: Zero-based index of the item to modify. example: "2" schema: type: integer requestBody: description: Update checklist item payload. content: application/json: schema: type: object properties: title: type: string description: The new title of the item. example: Gather information from server's logs. command: type: string description: The new slash command of the item. example: /jira update ticket required: - title - command x-codeSamples: - lang: curl source: | curl -X PUT 'http://localhost:8065/plugins/playbooks/api/v0/runs/6t7jdgyqr7b5sk24zkauhmrb06/checklists/1/item/0' \ -H 'Authorization: Bearer 9g64ig7q9pds8yjz8rsgd6e36e'\ -d '{"title": "Gather information from server's logs.", "command": "/jira update ticket"}' responses: "200": description: Item updated. "400": $ref: '#/components/responses/400' "500": $ref: '#/components/responses/500' delete: summary: Delete an item of a playbook run's checklist operationId: itemDelete security: - BearerAuth: [] tags: - PlaybookRuns parameters: - name: id in: path required: true description: ID of the playbook run whose checklist will be modified. example: zjy2q2iy2jafl0lo2oddos5xn7 schema: type: string - name: checklist in: path required: true description: Zero-based index of the checklist to modify. example: "1" schema: type: integer - name: item in: path required: true description: Zero-based index of the item to modify. example: "2" schema: type: integer x-codeSamples: - lang: curl source: | curl -X DELETE 'http://localhost:8065/plugins/playbooks/api/v0/runs/zjy2q2iy2jafl0lo2oddos5xn7/checklists/1/item/2' \ -H 'Authorization: Bearer 9g64ig7q9pds8yjz8rsgd6e36e' responses: "204": description: Item successfully deleted. "400": $ref: '#/components/responses/400' "500": $ref: '#/components/responses/500' /plugins/playbooks/api/v0/runs/{id}/checklists/{checklist}/item/{item}/state: put: summary: Update the state of an item operationId: itemSetState security: - BearerAuth: [] tags: - PlaybookRuns parameters: - name: id in: path required: true description: ID of the playbook run whose checklist will be modified. example: 7l37isroz4e63giev62hs318bn schema: type: string - name: checklist in: path required: true description: Zero-based index of the checklist to modify. example: "1" schema: type: integer - name: item in: path required: true description: Zero-based index of the item to modify. example: "2" schema: type: integer requestBody: description: Update checklist item's state payload. content: application/json: schema: type: object properties: new_state: type: string description: The new state of the item. enum: - "" - in_progress - closed example: closed default: "" required: - new_state x-codeSamples: - lang: curl source: | curl -X PUT 'http://localhost:8065/plugins/playbooks/api/v0/runs/7l37isroz4e63giev62hs318bn/checklists/1/item/2/state' \ -H 'Authorization: Bearer 9g64ig7q9pds8yjz8rsgd6e36e' -d '{"new_state": "closed"}' responses: "200": description: Item's state successfully updated. "400": $ref: '#/components/responses/400' "500": $ref: '#/components/responses/500' /plugins/playbooks/api/v0/runs/{id}/checklists/{checklist}/item/{item}/assignee: put: summary: Update the assignee of an item operationId: itemSetAssignee security: - BearerAuth: [] tags: - PlaybookRuns parameters: - name: id in: path required: true description: ID of the playbook run whose item will get a new assignee. example: 7l37isroz4e63giev62hs318bn schema: type: string - name: checklist in: path required: true description: Zero-based index of the checklist whose item will get a new assignee. example: "1" schema: type: integer - name: item in: path required: true description: Zero-based index of the item that will get a new assignee. example: "2" schema: type: integer requestBody: description: User ID of the new assignee. content: application/json: schema: type: object properties: assignee_id: type: string description: The user ID of the new assignee of the item. example: ruu86intseidqdxjojia41u7l1 required: - assignee_id x-codeSamples: - lang: curl source: | curl -X PUT 'http://localhost:8065/plugins/playbooks/api/v0/runs/7l37isroz4e63giev62hs318bn/checklists/1/item/2/assignee' \ -H 'Authorization: Bearer 9g64ig7q9pds8yjz8rsgd6e36e' -d '{"asignee_id": "ruu86intseidqdxjojia41u7l1"}' responses: "200": description: Item's assignee successfully updated. "400": $ref: '#/components/responses/400' "500": $ref: '#/components/responses/500' /plugins/playbooks/api/v0/runs/{id}/checklists/{checklist}/item/{item}/run: put: summary: Run an item's slash command operationId: itemRun security: - BearerAuth: [] tags: - PlaybookRuns parameters: - name: id in: path required: true description: ID of the playbook run whose item will be executed. example: 7l37isroz4e63giev62hs318bn schema: type: string - name: checklist in: path required: true description: Zero-based index of the checklist whose item will be executed. example: "1" schema: type: integer - name: item in: path required: true description: Zero-based index of the item whose slash command will be executed. example: "2" schema: type: integer x-codeSamples: - lang: curl source: | curl -X POST 'http://localhost:8065/plugins/playbooks/api/v0/runs/7l37isroz4e63giev62hs318bn/checklists/1/item/2/run' \ -H 'Authorization: Bearer 9g64ig7q9pds8yjz8rsgd6e36e' responses: "200": description: Item's slash command successfully executed. content: application/json: schema: $ref: '#/components/schemas/TriggerIdReturn' "400": $ref: '#/components/responses/400' "500": $ref: '#/components/responses/500' /plugins/playbooks/api/v0/runs/{id}/timeline/{event_id}/: delete: summary: Remove a timeline event from the playbook run operationId: removeTimelineEvent security: - BearerAuth: [] tags: - Timeline parameters: - name: id in: path required: true description: ID of the playbook run whose timeline event will be modified. example: zjy2q2iy2jafl0lo2oddos5xn7 schema: type: string - name: event_id in: path required: true description: ID of the timeline event to be deleted example: craxgf4r4trgzrtues3a1t74ac schema: type: string x-codeSamples: - lang: curl source: | curl -X DELETE 'http://localhost:8065/plugins/playbooks/api/v0/runs/zjy2q2iy2jafl0lo2oddos5xn7/timeline/craxgf4r4trgzrtues3a1t74ac' \ -H 'Authorization: Bearer 9g64ig7q9pds8yjz8rsgd6e36e' responses: "204": description: Item successfully deleted. "400": $ref: '#/components/responses/400' "500": $ref: '#/components/responses/500' /plugins/playbooks/api/v0/playbooks: get: summary: List all playbooks description: Retrieve a paged list of playbooks, filtered by team, and sorted by title, number of stages or number of steps. operationId: getPlaybooks security: - BearerAuth: [] tags: - Playbooks parameters: - name: team_id in: query description: ID of the team to filter by. required: true example: 08fmfasq5wit3qyfmq4mjk0rto schema: type: string - name: page in: query description: Zero-based index of the page to request. example: "3" schema: type: integer format: int32 default: 0 - name: per_page in: query description: Number of playbooks to return per page. example: "50" schema: type: integer format: int32 default: 1000 - name: sort in: query description: Field to sort the returned playbooks by title, number of stages or total number of steps. example: stages schema: type: string default: title enum: - title - stages - steps - name: direction in: query description: Direction (ascending or descending) followed by the sorting of the playbooks. example: asc schema: type: string default: asc enum: - desc - asc - name: with_archived in: query description: Includes archived playbooks in the result. example: "true" schema: type: boolean default: false x-codeSamples: - lang: curl source: | curl -X GET 'http://localhost:8065/plugins/playbooks/api/v0/playbooks?team_id=08fmfasq5wit3qyfmq4mjk0rto&sort=title&direction=asc' \ -H 'Authorization: Bearer 9g64ig7q9pds8yjz8rsgd6e36e' responses: "200": description: A paged list of playbooks. content: application/json: schema: $ref: '#/components/schemas/PlaybookList' "400": $ref: '#/components/responses/400' "403": $ref: '#/components/responses/403' "500": $ref: '#/components/responses/500' post: summary: Create a playbook operationId: createPlaybook security: - BearerAuth: [] tags: - Playbooks requestBody: description: Playbook content: application/json: schema: type: object required: - title - team_id - create_public_playbook_run - checklists - member_ids properties: title: type: string description: The title of the playbook. example: Cloud PlaybookRuns description: type: string description: The description of the playbook. example: A playbook to follow when there is a playbook run regarding the availability of the cloud service. team_id: type: string description: The identifier of the team where the playbook is in. example: p03rbi6viyztysbqnkvcqyel2i create_public_playbook_run: type: boolean description: A boolean indicating whether the playbook runs created from this playbook should be public or private. example: true public: type: boolean description: A boolean indicating whether the playbook is licensed as public or private. Required 'true' for free tier. example: true checklists: type: array description: The stages defined by this playbook. items: type: object required: - title - items properties: title: type: string description: The title of the checklist. example: Triage issue items: type: array description: The list of tasks to do. items: type: object required: - title properties: title: type: string description: The title of the checklist item. example: Gather information from customer. command: type: string description: The slash command associated with this item. If the item has no slash command associated, this is an empty string example: /opsgenie on-call description: type: string description: A detailed description of the checklist item, formatted with Markdown. example: Ask the customer for more information in [Zendesk](https://www.zendesk.com/). member_ids: description: The identifiers of all the users that are members of this playbook. type: array items: type: string description: User ID of the playbook member. example: ilh6s1j4yefbdhxhtlzt179i6m example: ilh6s1j4yefbdhxhtlzt179i6m broadcast_channel_ids: description: The IDs of the channels where all the status updates will be broadcasted. The team of the broadcast channel must be the same as the playbook's team. type: array items: type: string description: ID of the broadcast channel. example: 2zh7rpashwfwapwaqyslmhwbax example: 2zh7rpashwfwapwaqyslmhwbax invited_user_ids: description: A list with the IDs of the members to be automatically invited to the playbook run's channel as soon as the playbook run is created. type: array items: type: string description: User ID of the member to be invited. example: 01kidjn9iozv7bist427w4gkjo example: 01kidjn9iozv7bist427w4gkjo invite_users_enabled: description: Boolean that indicates whether the members declared in invited_user_ids will be automatically invited. type: boolean example: true default_owner_id: description: User ID of the member that will be automatically assigned as owner as soon as the playbook run is created. If the member is not part of the playbook run's channel or is not included in the invited_user_ids list, they will be automatically invited to the channel. type: string example: 9dtruav6d9ce3oqnc5pwhtqtfq default_owner_enabled: description: Boolean that indicates whether the member declared in default_owner_id will be automatically assigned as owner. type: string example: true announcement_channel_id: description: ID of the channel where the playbook run will be automatically announced as soon as the playbook run is created. type: string example: 8iofau5swv32l6qtk3vlxgobta announcement_channel_enabled: description: Boolean that indicates whether the playbook run creation will be announced in the channel declared in announcement_channel_id. type: boolean example: true webhook_on_creation_url: description: An absolute URL where a POST request will be sent as soon as the playbook run is created. The allowed protocols are HTTP and HTTPS. type: string example: https://httpbin.org/post webhook_on_creation_enabled: description: Boolean that indicates whether the webhook declared in webhook_on_creation_url will be automatically sent. type: boolean example: true webhook_on_status_update_url: description: An absolute URL where a POST request will be sent as soon as the playbook run's status is updated. The allowed protocols are HTTP and HTTPS. type: string example: https://httpbin.org/post webhook_on_status_update_enabled: description: Boolean that indicates whether the webhook declared in webhook_on_status_update_url will be automatically sent. type: boolean example: true x-codeSamples: - lang: curl source: | curl -X POST 'http://localhost:8065/plugins/playbooks/api/v0/playbooks' \ -H 'Authorization: Bearer 9g64ig7q9pds8yjz8rsgd6e36e'\ -d '{"title": "Cloud PlaybookRuns", "description": "A playbook to follow when there is a playbook run regarding the availability of the cloud service.", "team_id": "p03rbi6viyztysbqnkvcqyel2i","create_public_playbook_run": true,"checklists": [{"title": "Triage issue","items": [{"title": "Gather information from customer."}]}]}' callbacks: playbookRunCreation: '{$request.body#/webhook_on_creation_url}': post: summary: PlaybookRun's creation outgoing webhook. description: When a playbook run is created with this playbook, a POST request is sent to the URL configured in webhook_on_creation_url. The webhook is considered successful if your server returns a response code within the 200-299 range. Otherwise, the webhook is considered failed, and a warning message is posted in the playbook run's channel. No retries are made. operationId: webhookOncreation requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WebhookOnCreationPayload' responses: 2XX: description: Your server returns a 2XX code if it successfully received the request. playbookRunStatusUpdate: '{$request.body#/webhook_on_status_update_url}': post: summary: PlaybookRun's status update outgoing webhook. description: When a playbook run's status is updated, a POST request is sent to the URL configured in webhook_on_status_update_url. The webhook is considered successful if your server returns a response code within the 200-299 range. Otherwise, the webhook is considered failed, and a warning message is posted in the playbook run's channel. No retries are made. operationId: webhookOnStatusUpdate requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WebhookOnStatusUpdatePayload' responses: 2XX: description: Your server returns a 2XX code if it successfully received the request. responses: "201": description: ID of the created playbook. headers: Location: description: Location of the created playbook. schema: type: string example: /api/v0/playbook/cdl5o0tjcp5rqlpjidhobj64nd example: /api/v0/playbook/cdl5o0tjcp5rqlpjidhobj64nd content: application/json: schema: type: object properties: id: type: string example: iz0g457ikesz55dhxcfa0fk9yy required: - id "400": $ref: '#/components/responses/400' "403": $ref: '#/components/responses/403' "500": $ref: '#/components/responses/500' /plugins/playbooks/api/v0/playbooks/{id}: get: summary: Get a playbook operationId: getPlaybook security: - BearerAuth: [] tags: - Playbooks parameters: - name: id in: path required: true description: ID of the playbook to retrieve. schema: type: string example: iz0g457ikesz55dhxcfa0fk9yy example: iz0g457ikesz55dhxcfa0fk9yy x-codeSamples: - lang: curl source: | curl -X GET 'http://localhost:8065/plugins/playbooks/api/v0/playbooks/iz0g457ikesz55dhxcfa0fk9yy' \ -H 'Authorization: Bearer 9g64ig7q9pds8yjz8rsgd6e36e' responses: "200": description: Playbook. content: application/json: schema: $ref: '#/components/schemas/Playbook' "403": $ref: '#/components/responses/403' "500": $ref: '#/components/responses/500' put: summary: Update a playbook operationId: updatePlaybook security: - BearerAuth: [] tags: - Playbooks parameters: - name: id in: path required: true description: ID of the playbook to update. schema: type: string example: iz0g457ikesz55dhxcfa0fk9yy example: iz0g457ikesz55dhxcfa0fk9yy requestBody: description: Playbook payload content: application/json: schema: $ref: '#/components/schemas/Playbook' x-codeSamples: - lang: curl source: | curl -X PUT 'http://localhost:8065/plugins/playbooks/api/v0/playbooks/iz0g457ikesz55dhxcfa0fk9yy' \ -H 'Authorization: Bearer 9g64ig7q9pds8yjz8rsgd6e36e'\ -d '{"title": "Playbook","team_id": "ni8duypfe7bamprxqeffd563gy","create_public_playbook_run": true,"checklists": [{"title": "Title","items": [{"title": "Title"}]}]}' responses: "200": description: Playbook succesfully updated. "400": $ref: '#/components/responses/400' "403": $ref: '#/components/responses/403' "500": $ref: '#/components/responses/500' delete: summary: Delete a playbook operationId: deletePlaybook security: - BearerAuth: [] tags: - Playbooks parameters: - name: id in: path required: true description: ID of the playbook to delete. schema: type: string example: iz0g457ikesz55dhxcfa0fk9yy example: iz0g457ikesz55dhxcfa0fk9yy x-codeSamples: - lang: curl source: | curl -X DELETE 'http://localhost:8065/plugins/playbooks/api/v0/playbooks/iz0g457ikesz55dhxcfa0fk9yy' \ -H 'Authorization: Bearer 9g64ig7q9pds8yjz8rsgd6e36e' responses: "204": description: Playbook successfully deleted. "403": $ref: '#/components/responses/403' "500": $ref: '#/components/responses/500' /plugins/playbooks/api/v0/playbooks/{id}/autofollows: get: summary: Get the list of followers' user IDs of a playbook operationId: getAutoFollows security: - BearerAuth: [] tags: - PlaybookAutofollows parameters: - name: id in: path required: true description: ID of the playbook to retrieve followers from. schema: type: string example: iz0g457ikesz55dhxcfa0fk9yy example: iz0g457ikesz55dhxcfa0fk9yy x-codeSamples: - lang: curl source: | curl -X GET 'http://localhost:8065/plugins/playbooks/api/v0/playbooks/iz0g457ikesz55dhxcfa0fk9yy/autofollows' \ -H 'Authorization: Bearer 9g64ig7q9pds8yjz8rsgd6e36e' responses: "200": description: List of the user IDs who follow the playbook. content: application/json: schema: $ref: '#/components/schemas/PlaybookAutofollows' "403": $ref: '#/components/responses/403' "500": $ref: '#/components/responses/500' components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: Token BearerAuth: type: http scheme: bearer responses: "400": content: application/json: schema: $ref: '#/components/schemas/Error' description: The request is malformed. "403": content: application/json: schema: $ref: '#/components/schemas/Error' description: Access to the resource is forbidden for this user. "404": content: application/json: schema: $ref: '#/components/schemas/Error' description: Resource requested not found. "500": content: application/json: schema: $ref: '#/components/schemas/Error' description: There was an internal error in the server. Forbidden: description: Do not have appropriate permissions content: application/json: schema: $ref: '#/components/schemas/AppError' Unauthorized: description: No access token provided content: application/json: schema: $ref: '#/components/schemas/AppError' BadRequest: description: Invalid or missing parameters in URL or request body content: application/json: schema: $ref: '#/components/schemas/AppError' NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/AppError' TooLarge: description: Content too large content: application/json: schema: $ref: '#/components/schemas/AppError' NotImplemented: description: Feature is disabled content: application/json: schema: $ref: '#/components/schemas/AppError' TooManyRequests: description: Too many requests content: application/json: schema: $ref: '#/components/schemas/AppError' InternalServerError: description: Something went wrong with the server content: application/json: schema: $ref: '#/components/schemas/AppError' BadGateway: description: Bad gateway content: application/json: schema: $ref: '#/components/schemas/AppError' schemas: User: type: object properties: id: type: string create_at: description: The time in milliseconds a user was created type: integer format: int64 update_at: description: The time in milliseconds a user was last updated type: integer format: int64 delete_at: description: The time in milliseconds a user was deleted type: integer format: int64 username: type: string first_name: type: string last_name: type: string nickname: type: string email: type: string email_verified: type: boolean auth_service: type: string roles: type: string locale: type: string notify_props: $ref: '#/components/schemas/UserNotifyProps' props: type: object last_password_update: type: integer format: int64 last_picture_update: type: integer format: int64 failed_attempts: type: integer mfa_active: type: boolean timezone: $ref: '#/components/schemas/Timezone' terms_of_service_id: description: ID of accepted terms of service, if any. This field is not present if empty. type: string terms_of_service_create_at: description: The time in milliseconds the user accepted the terms of service type: integer format: int64 UsersStats: type: object properties: total_users_count: type: integer KnownUsers: type: array properties: items: type: string Team: type: object properties: id: type: string create_at: description: The time in milliseconds a team was created type: integer format: int64 update_at: description: The time in milliseconds a team was last updated type: integer format: int64 delete_at: description: The time in milliseconds a team was deleted type: integer format: int64 display_name: type: string name: type: string description: type: string email: type: string type: type: string allowed_domains: type: string invite_id: type: string allow_open_invite: type: boolean policy_id: type: string description: The data retention policy to which this team has been assigned. If no such policy exists, or the caller does not have the `sysconsole_read_compliance_data_retention` permission, this field will be null. TeamStats: type: object properties: team_id: type: string total_member_count: type: integer active_member_count: type: integer TeamExists: type: object properties: exists: type: boolean Channel: type: object properties: id: type: string create_at: description: The time in milliseconds a channel was created type: integer format: int64 update_at: description: The time in milliseconds a channel was last updated type: integer format: int64 delete_at: description: The time in milliseconds a channel was deleted type: integer format: int64 team_id: type: string type: type: string display_name: type: string name: type: string header: type: string purpose: type: string last_post_at: description: The time in milliseconds of the last post of a channel type: integer format: int64 total_msg_count: type: integer extra_update_at: description: Deprecated in Mattermost 5.0 release type: integer format: int64 creator_id: type: string ChannelStats: type: object properties: channel_id: type: string member_count: type: integer ChannelMember: type: object properties: channel_id: type: string user_id: type: string roles: type: string last_viewed_at: description: The time in milliseconds the channel was last viewed by the user type: integer format: int64 msg_count: type: integer mention_count: type: integer notify_props: $ref: '#/components/schemas/ChannelNotifyProps' last_update_at: description: The time in milliseconds the channel member was last updated type: integer format: int64 ChannelMemberWithTeamData: allOf: - $ref: '#/components/schemas/ChannelMember' - type: object properties: team_display_name: type: string description: The display name of the team to which this channel belongs. team_name: type: string description: The name of the team to which this channel belongs. team_update_at: type: integer description: The time at which the team to which this channel belongs was last updated. ChannelData: type: object properties: channel: $ref: '#/components/schemas/Channel' member: $ref: '#/components/schemas/ChannelMember' ChannelWithTeamData: allOf: - $ref: '#/components/schemas/Channel' - type: object properties: team_display_name: type: string description: The display name of the team to which this channel belongs. team_name: type: string description: The name of the team to which this channel belongs. team_update_at: type: integer description: The time at which the team to which this channel belongs was last updated. policy_id: type: string description: The data retention policy to which this team has been assigned. If no such policy exists, or the caller does not have the `sysconsole_read_compliance_data_retention` permission, this field will be null. ChannelListWithTeamData: type: array items: $ref: '#/components/schemas/ChannelWithTeamData' ChannelBookmark: type: object properties: id: type: string create_at: description: The time in milliseconds a channel bookmark was created type: integer format: int64 update_at: description: The time in milliseconds a channel bookmark was last updated type: integer format: int64 delete_at: description: The time in milliseconds a channel bookmark was deleted type: integer format: int64 channel_id: type: string owner_id: description: The ID of the user that the channel bookmark belongs to type: string file_id: description: The ID of the file associated with the channel bookmark type: string display_name: type: string sort_order: description: The order of the channel bookmark type: integer format: int64 link_url: description: The URL associated with the channel bookmark type: string image_url: description: The URL of the image associated with the channel bookmark type: string emoji: type: string type: type: string enum: - link - file original_id: description: The ID of the original channel bookmark type: string parent_id: description: The ID of the parent channel bookmark type: string ChannelBookmarkWithFileInfo: allOf: - $ref: '#/components/schemas/ChannelBookmark' - type: object properties: file: $ref: '#/components/schemas/FileInfo' UpdateChannelBookmarkResponse: type: object properties: updated: $ref: '#/components/schemas/ChannelBookmarkWithFileInfo' deleted: $ref: '#/components/schemas/ChannelBookmarkWithFileInfo' Post: type: object properties: id: type: string create_at: description: The time in milliseconds a post was created type: integer format: int64 update_at: description: The time in milliseconds a post was last updated type: integer format: int64 delete_at: description: The time in milliseconds a post was deleted type: integer format: int64 edit_at: type: integer format: int64 user_id: type: string channel_id: type: string root_id: type: string original_id: type: string message: type: string type: type: string props: type: object hashtag: type: string file_ids: type: array items: type: string pending_post_id: type: string metadata: $ref: '#/components/schemas/PostMetadata' FileInfoList: type: object properties: order: type: array items: type: string example: - file_info_id1 - file_info_id2 file_infos: type: object additionalProperties: $ref: '#/components/schemas/FileInfo' next_file_id: type: string description: The ID of next file info. Not omitted when empty or not relevant. prev_file_id: type: string description: The ID of previous file info. Not omitted when empty or not relevant. PostList: type: object properties: order: type: array items: type: string example: - post_id1 - post_id12 posts: type: object additionalProperties: $ref: '#/components/schemas/Post' next_post_id: type: string description: The ID of next post. Not omitted when empty or not relevant. prev_post_id: type: string description: The ID of previous post. Not omitted when empty or not relevant. has_next: type: boolean description: Whether there are more items after this page. PostListWithSearchMatches: type: object properties: order: type: array items: type: string example: - post_id1 - post_id12 posts: type: object additionalProperties: $ref: '#/components/schemas/Post' matches: description: A mapping of post IDs to a list of matched terms within the post. This field will only be populated on servers running version 5.1 or greater with Elasticsearch enabled. type: object additionalProperties: type: array items: type: string example: post_id1: - search match 1 - search match 2 PostMetadata: type: object description: Additional information used to display a post. properties: embeds: type: array description: | Information about content embedded in the post including OpenGraph previews, image link previews, and message attachments. This field will be null if the post does not contain embedded content. items: type: object properties: type: type: string description: The type of content that is embedded in this point. enum: - image - message_attachment - opengraph - link url: type: string description: The URL of the embedded content, if one exists. data: type: object description: | Any additional information about the embedded content. Only used at this time to store OpenGraph metadata. This field will be null for non-OpenGraph embeds. emojis: type: array description: | The custom emojis that appear in this point or have been used in reactions to this post. This field will be null if the post does not contain custom emojis. items: $ref: '#/components/schemas/Emoji' files: type: array description: | The FileInfo objects for any files attached to the post. This field will be null if the post does not have any file attachments. items: $ref: '#/components/schemas/FileInfo' images: type: object description: | An object mapping the URL of an external image to an object containing the dimensions of that image. This field will be null if the post or its embedded content does not reference any external images. items: type: object properties: height: type: integer width: type: integer reactions: type: array description: | Any reactions made to this point. This field will be null if no reactions have been made to this post. items: $ref: '#/components/schemas/Reaction' priority: type: object description: | Post priority set for this post. This field will be null if no priority metadata has been set. properties: priority: type: string description: The priority label of a post, could be either empty, important, or urgent. requested_ack: type: boolean description: Whether the post author has requested for acknowledgements or not. acknowledgements: type: array description: | Any acknowledgements made to this point. items: $ref: '#/components/schemas/PostAcknowledgement' TeamMap: type: object description: A mapping of teamIds to teams. properties: team_id: $ref: '#/components/schemas/Team' TeamMember: type: object properties: team_id: description: The ID of the team this member belongs to. type: string user_id: description: The ID of the user this member relates to. type: string roles: description: The complete list of roles assigned to this team member, as a space-separated list of role names, including any roles granted implicitly through permissions schemes. type: string delete_at: description: The time in milliseconds that this team member was deleted. type: integer scheme_user: description: Whether this team member holds the default user role defined by the team's permissions scheme. type: boolean scheme_admin: description: Whether this team member holds the default admin role defined by the team's permissions scheme. type: boolean explicit_roles: description: The list of roles explicitly assigned to this team member, as a space separated list of role names. This list does *not* include any roles granted implicitly through permissions schemes. type: string TeamUnread: type: object properties: team_id: type: string msg_count: type: integer mention_count: type: integer ChannelUnread: type: object properties: team_id: type: string channel_id: type: string msg_count: type: integer mention_count: type: integer ChannelUnreadAt: type: object properties: team_id: description: The ID of the team the channel belongs to. type: string channel_id: description: The ID of the channel the user has access to.. type: string msg_count: description: No. of messages the user has already read. type: integer mention_count: description: No. of mentions the user has within the unread posts of the channel. type: integer last_viewed_at: description: time in milliseconds when the user last viewed the channel. type: integer Session: type: object properties: create_at: description: The time in milliseconds a session was created type: integer format: int64 device_id: type: string expires_at: description: The time in milliseconds a session will expire type: integer format: int64 id: type: string is_oauth: type: boolean last_activity_at: description: The time in milliseconds of the last activity of a session type: integer format: int64 props: type: object roles: type: string team_members: type: array items: $ref: '#/components/schemas/TeamMember' token: type: string user_id: type: string FileInfo: type: object properties: id: description: The unique identifier for this file type: string user_id: description: The ID of the user that uploaded this file type: string post_id: description: If this file is attached to a post, the ID of that post type: string create_at: description: The time in milliseconds a file was created type: integer format: int64 update_at: description: The time in milliseconds a file was last updated type: integer format: int64 delete_at: description: The time in milliseconds a file was deleted type: integer format: int64 name: description: The name of the file type: string extension: description: The extension at the end of the file name type: string size: description: The size of the file in bytes type: integer mime_type: description: The MIME type of the file type: string width: description: If this file is an image, the width of the file type: integer height: description: If this file is an image, the height of the file type: integer has_preview_image: description: If this file is an image, whether or not it has a preview-sized version type: boolean Preference: type: object properties: user_id: description: The ID of the user that owns this preference type: string category: type: string name: type: string value: type: string UserAuthData: type: object properties: auth_data: description: Service-specific authentication data type: string auth_service: description: The authentication service such as "email", "gitlab", or "ldap" type: string required: - auth_data - auth_service UserAutocomplete: type: object properties: users: description: A list of users that are the main result of the query type: array items: $ref: '#/components/schemas/User' out_of_channel: description: A special case list of users returned when autocompleting in a specific channel. Omitted when empty or not relevant type: array items: $ref: '#/components/schemas/User' UserAutocompleteInTeam: type: object properties: in_team: description: A list of user objects in the team type: array items: $ref: '#/components/schemas/User' UserAutocompleteInChannel: type: object properties: in_channel: description: A list of user objects in the channel type: array items: $ref: '#/components/schemas/User' out_of_channel: description: A list of user objects not in the channel type: array items: $ref: '#/components/schemas/User' IncomingWebhook: type: object properties: id: description: The unique identifier for this incoming webhook type: string create_at: description: The time in milliseconds a incoming webhook was created type: integer format: int64 update_at: description: The time in milliseconds a incoming webhook was last updated type: integer format: int64 delete_at: description: The time in milliseconds a incoming webhook was deleted type: integer format: int64 channel_id: description: The ID of a public channel or private group that receives the webhook payloads type: string description: description: The description for this incoming webhook type: string display_name: description: The display name for this incoming webhook type: string OutgoingWebhook: type: object properties: id: description: The unique identifier for this outgoing webhook type: string create_at: description: The time in milliseconds a outgoing webhook was created type: integer format: int64 update_at: description: The time in milliseconds a outgoing webhook was last updated type: integer format: int64 delete_at: description: The time in milliseconds a outgoing webhook was deleted type: integer format: int64 creator_id: description: The Id of the user who created the webhook type: string team_id: description: The ID of the team that the webhook watchs type: string channel_id: description: The ID of a public channel that the webhook watchs type: string description: description: The description for this outgoing webhook type: string display_name: description: The display name for this outgoing webhook type: string trigger_words: description: List of words for the webhook to trigger on type: array items: type: string trigger_when: description: When to trigger the webhook, `0` when a trigger word is present at all and `1` if the message starts with a trigger word type: integer callback_urls: description: The URLs to POST the payloads to when the webhook is triggered type: array items: type: string content_type: description: The format to POST the data in, either `application/json` or `application/x-www-form-urlencoded` default: application/x-www-form-urlencoded type: string Reaction: type: object properties: user_id: description: The ID of the user that made this reaction type: string post_id: description: The ID of the post to which this reaction was made type: string emoji_name: description: The name of the emoji that was used for this reaction type: string create_at: description: The time in milliseconds this reaction was made type: integer format: int64 NewTeamMember: type: object properties: id: description: The user's ID. type: string username: type: string first_name: type: string last_name: type: string nickname: type: string position: description: The user's position field value. type: string create_at: description: The creation timestamp of the team member record. type: integer NewTeamMembersList: type: object properties: has_next: description: Indicates if there is another page of new team members that can be fetched. type: boolean items: description: List of new team members. type: array items: $ref: '#/components/schemas/NewTeamMember' total_count: description: The total count of new team members for the given time range. type: integer Emoji: type: object properties: id: description: The ID of the emoji type: string creator_id: description: The ID of the user that made the emoji type: string name: description: The name of the emoji type: string create_at: description: The time in milliseconds the emoji was made type: integer format: int64 update_at: description: The time in milliseconds the emoji was last updated type: integer format: int64 delete_at: description: The time in milliseconds the emoji was deleted type: integer format: int64 Command: type: object properties: id: description: The ID of the slash command type: string token: description: The token which is used to verify the source of the payload type: string create_at: description: The time in milliseconds the command was created type: integer update_at: description: The time in milliseconds the command was last updated type: integer format: int64 delete_at: description: The time in milliseconds the command was deleted, 0 if never deleted type: integer format: int64 creator_id: description: The user id for the commands creator type: string team_id: description: The team id for which this command is configured type: string trigger: description: The string that triggers this command type: string method: description: Is the trigger done with HTTP Get ('G') or HTTP Post ('P') type: string username: description: What is the username for the response post type: string icon_url: description: The url to find the icon for this users avatar type: string auto_complete: description: Use auto complete for this command type: boolean auto_complete_desc: description: The description for this command shown when selecting the command type: string auto_complete_hint: description: The hint for this command type: string display_name: description: Display name for the command type: string description: description: Description for this command type: string url: description: The URL that is triggered type: string AutocompleteSuggestion: type: object properties: Complete: description: Completed suggestion type: string Suggestion: description: Predicted text user might want to input type: string Hint: description: Hint about suggested input type: string Description: description: Description of the suggested command type: string IconData: description: Base64 encoded svg image type: string CommandResponse: type: object properties: ResponseType: description: The response type either in_channel or ephemeral type: string Text: type: string Username: type: string IconURL: type: string GotoLocation: type: string Attachments: type: array items: $ref: '#/components/schemas/SlackAttachment' SlackAttachment: type: object properties: Id: type: string Fallback: type: string Color: type: string Pretext: type: string AuthorName: type: string AuthorLink: type: string AuthorIcon: type: string Title: type: string TitleLink: type: string Text: type: string Fields: type: array items: $ref: '#/components/schemas/SlackAttachmentField' ImageURL: type: string ThumbURL: type: string Footer: type: string FooterIcon: type: string Timestamp: description: The timestamp of the slack attachment, either type of string or integer type: string SlackAttachmentField: type: object properties: Title: type: string Value: description: The value of the attachment, set as string but capable with golang interface type: string Short: type: boolean StatusOK: type: object properties: status: description: Will contain "ok" if the request was successful and there was nothing else to return type: string OpenGraph: type: object description: OpenGraph metadata of a webpage properties: type: type: string url: type: string title: type: string description: type: string determiner: type: string site_name: type: string locale: type: string locales_alternate: type: array items: type: string images: type: array items: type: object description: Image object used in OpenGraph metadata of a webpage properties: url: type: string secure_url: type: string type: type: string width: type: integer height: type: integer videos: type: array items: type: object description: Video object used in OpenGraph metadata of a webpage properties: url: type: string secure_url: type: string type: type: string width: type: integer height: type: integer audios: type: array items: type: object description: Audio object used in OpenGraph metadata of a webpage properties: url: type: string secure_url: type: string type: type: string article: type: object description: Article object used in OpenGraph metadata of a webpage, if type is article properties: published_time: type: string modified_time: type: string expiration_time: type: string section: type: string tags: type: array items: type: string authors: type: array items: type: object properties: first_name: type: string last_name: type: string username: type: string gender: type: string book: type: object description: Book object used in OpenGraph metadata of a webpage, if type is book properties: isbn: type: string release_date: type: string tags: type: array items: type: string authors: type: array items: type: object properties: first_name: type: string last_name: type: string username: type: string gender: type: string profile: type: object properties: first_name: type: string last_name: type: string username: type: string gender: type: string Audit: type: object properties: id: type: string create_at: description: The time in milliseconds a audit was created type: integer format: int64 user_id: type: string action: type: string extra_info: type: string ip_address: type: string session_id: type: string Config: type: object properties: ServiceSettings: type: object properties: SiteURL: type: string ListenAddress: type: string ConnectionSecurity: type: string TLSCertFile: type: string TLSKeyFile: type: string UseLetsEncrypt: type: boolean LetsEncryptCertificateCacheFile: type: string Forward80To443: type: boolean ReadTimeout: type: integer WriteTimeout: type: integer MaximumLoginAttempts: type: integer SegmentDeveloperKey: type: string GoogleDeveloperKey: type: string EnableOAuthServiceProvider: type: boolean EnableIncomingWebhooks: type: boolean EnableOutgoingWebhooks: type: boolean EnableCommands: type: boolean EnableOnlyAdminIntegrations: type: boolean EnablePostUsernameOverride: type: boolean EnablePostIconOverride: type: boolean EnableTesting: type: boolean EnableDeveloper: type: boolean EnableSecurityFixAlert: type: boolean EnableInsecureOutgoingConnections: type: boolean EnableMultifactorAuthentication: type: boolean EnforceMultifactorAuthentication: type: boolean AllowCorsFrom: type: string SessionLengthWebInDays: type: integer SessionLengthMobileInDays: type: integer SessionLengthSSOInDays: type: integer SessionCacheInMinutes: type: integer WebsocketSecurePort: type: integer WebsocketPort: type: integer WebserverMode: type: string EnableCustomEmoji: type: boolean RestrictCustomEmojiCreation: type: string TeamSettings: type: object properties: SiteName: type: string MaxUsersPerTeam: type: integer EnableTeamCreation: type: boolean EnableUserCreation: type: boolean EnableOpenServer: type: boolean RestrictCreationToDomains: type: string EnableCustomBrand: type: boolean CustomBrandText: type: string CustomDescriptionText: type: string RestrictDirectMessage: type: string RestrictTeamInvite: type: string RestrictPublicChannelManagement: type: string RestrictPrivateChannelManagement: type: string RestrictPublicChannelCreation: type: string RestrictPrivateChannelCreation: type: string RestrictPublicChannelDeletion: type: string RestrictPrivateChannelDeletion: type: string UserStatusAwayTimeout: type: integer MaxChannelsPerTeam: type: integer MaxNotificationsPerChannel: type: integer SqlSettings: type: object properties: DriverName: type: string DataSource: type: string DataSourceReplicas: type: array items: type: string MaxIdleConns: type: integer MaxOpenConns: type: integer Trace: type: boolean AtRestEncryptKey: type: string LogSettings: type: object properties: EnableConsole: type: boolean ConsoleLevel: type: string EnableFile: type: boolean FileLevel: type: string FileLocation: type: string EnableWebhookDebugging: type: boolean EnableDiagnostics: type: boolean PasswordSettings: type: object properties: MinimumLength: type: integer Lowercase: type: boolean Number: type: boolean Uppercase: type: boolean Symbol: type: boolean FileSettings: type: object properties: MaxFileSize: type: integer DriverName: type: string Directory: type: string EnablePublicLink: type: boolean PublicLinkSalt: type: string ThumbnailWidth: type: integer ThumbnailHeight: type: integer PreviewWidth: type: integer PreviewHeight: type: integer ProfileWidth: type: integer ProfileHeight: type: integer InitialFont: type: string AmazonS3AccessKeyId: type: string AmazonS3SecretAccessKey: type: string AmazonS3Bucket: type: string AmazonS3Region: type: string AmazonS3Endpoint: type: string AmazonS3SSL: type: boolean EmailSettings: type: object properties: EnableSignUpWithEmail: type: boolean EnableSignInWithEmail: type: boolean EnableSignInWithUsername: type: boolean SendEmailNotifications: type: boolean RequireEmailVerification: type: boolean FeedbackName: type: string FeedbackEmail: type: string FeedbackOrganization: type: string SMTPUsername: type: string SMTPPassword: type: string SMTPServer: type: string SMTPPort: type: string ConnectionSecurity: type: string InviteSalt: type: string PasswordResetSalt: type: string SendPushNotifications: type: boolean PushNotificationServer: type: string PushNotificationContents: type: string EnableEmailBatching: type: boolean EmailBatchingBufferSize: type: integer EmailBatchingInterval: type: integer RateLimitSettings: type: object properties: Enable: type: boolean PerSec: type: integer MaxBurst: type: integer MemoryStoreSize: type: integer VaryByRemoteAddr: type: boolean VaryByHeader: type: string PrivacySettings: type: object properties: ShowEmailAddress: type: boolean ShowFullName: type: boolean SupportSettings: type: object properties: TermsOfServiceLink: type: string PrivacyPolicyLink: type: string AboutLink: type: string HelpLink: type: string ReportAProblemLink: type: string SupportEmail: type: string GitLabSettings: type: object properties: Enable: type: boolean Secret: type: string Id: type: string Scope: type: string AuthEndpoint: type: string TokenEndpoint: type: string UserApiEndpoint: type: string GoogleSettings: type: object properties: Enable: type: boolean Secret: type: string Id: type: string Scope: type: string AuthEndpoint: type: string TokenEndpoint: type: string UserApiEndpoint: type: string Office365Settings: type: object properties: Enable: type: boolean Secret: type: string Id: type: string Scope: type: string AuthEndpoint: type: string TokenEndpoint: type: string UserApiEndpoint: type: string LdapSettings: type: object properties: Enable: type: boolean LdapServer: type: string LdapPort: type: integer ConnectionSecurity: type: string BaseDN: type: string BindUsername: type: string BindPassword: type: string UserFilter: type: string FirstNameAttribute: type: string LastNameAttribute: type: string EmailAttribute: type: string UsernameAttribute: type: string NicknameAttribute: type: string IdAttribute: type: string PositionAttribute: type: string SyncIntervalMinutes: type: integer SkipCertificateVerification: type: boolean QueryTimeout: type: integer MaxPageSize: type: integer LoginFieldName: type: string ComplianceSettings: type: object properties: Enable: type: boolean Directory: type: string EnableDaily: type: boolean LocalizationSettings: type: object properties: DefaultServerLocale: type: string DefaultClientLocale: type: string AvailableLocales: type: string SamlSettings: type: object properties: Enable: type: boolean Verify: type: boolean Encrypt: type: boolean IdpUrl: type: string IdpDescriptorUrl: type: string AssertionConsumerServiceURL: type: string IdpCertificateFile: type: string PublicCertificateFile: type: string PrivateKeyFile: type: string FirstNameAttribute: type: string LastNameAttribute: type: string EmailAttribute: type: string UsernameAttribute: type: string NicknameAttribute: type: string LocaleAttribute: type: string PositionAttribute: type: string LoginButtonText: type: string NativeAppSettings: type: object properties: AppDownloadLink: type: string AndroidAppDownloadLink: type: string IosAppDownloadLink: type: string ClusterSettings: type: object properties: Enable: type: boolean InterNodeListenAddress: type: string InterNodeUrls: type: array items: type: string MetricsSettings: type: object properties: Enable: type: boolean BlockProfileRate: type: integer ListenAddress: type: string AnalyticsSettings: type: object properties: MaxUsersForStatistics: type: integer EnvironmentConfig: type: object properties: ServiceSettings: type: object properties: SiteURL: type: boolean ListenAddress: type: boolean ConnectionSecurity: type: boolean TLSCertFile: type: boolean TLSKeyFile: type: boolean UseLetsEncrypt: type: boolean LetsEncryptCertificateCacheFile: type: boolean Forward80To443: type: boolean ReadTimeout: type: boolean WriteTimeout: type: boolean MaximumLoginAttempts: type: boolean SegmentDeveloperKey: type: boolean GoogleDeveloperKey: type: boolean EnableOAuthServiceProvider: type: boolean EnableIncomingWebhooks: type: boolean EnableOutgoingWebhooks: type: boolean EnableCommands: type: boolean EnableOnlyAdminIntegrations: type: boolean EnablePostUsernameOverride: type: boolean EnablePostIconOverride: type: boolean EnableTesting: type: boolean EnableDeveloper: type: boolean EnableSecurityFixAlert: type: boolean EnableInsecureOutgoingConnections: type: boolean EnableMultifactorAuthentication: type: boolean EnforceMultifactorAuthentication: type: boolean AllowCorsFrom: type: boolean SessionLengthWebInDays: type: boolean SessionLengthMobileInDays: type: boolean SessionLengthSSOInDays: type: boolean SessionCacheInMinutes: type: boolean WebsocketSecurePort: type: boolean WebsocketPort: type: boolean WebserverMode: type: boolean EnableCustomEmoji: type: boolean RestrictCustomEmojiCreation: type: boolean TeamSettings: type: object properties: SiteName: type: boolean MaxUsersPerTeam: type: boolean EnableTeamCreation: type: boolean EnableUserCreation: type: boolean EnableOpenServer: type: boolean RestrictCreationToDomains: type: boolean EnableCustomBrand: type: boolean CustomBrandText: type: boolean CustomDescriptionText: type: boolean RestrictDirectMessage: type: boolean RestrictTeamInvite: type: boolean RestrictPublicChannelManagement: type: boolean RestrictPrivateChannelManagement: type: boolean RestrictPublicChannelCreation: type: boolean RestrictPrivateChannelCreation: type: boolean RestrictPublicChannelDeletion: type: boolean RestrictPrivateChannelDeletion: type: boolean UserStatusAwayTimeout: type: boolean MaxChannelsPerTeam: type: boolean MaxNotificationsPerChannel: type: boolean SqlSettings: type: object properties: DriverName: type: boolean DataSource: type: boolean DataSourceReplicas: type: boolean MaxIdleConns: type: boolean MaxOpenConns: type: boolean Trace: type: boolean AtRestEncryptKey: type: boolean LogSettings: type: object properties: EnableConsole: type: boolean ConsoleLevel: type: boolean EnableFile: type: boolean FileLevel: type: boolean FileLocation: type: boolean EnableWebhookDebugging: type: boolean EnableDiagnostics: type: boolean PasswordSettings: type: object properties: MinimumLength: type: boolean Lowercase: type: boolean Number: type: boolean Uppercase: type: boolean Symbol: type: boolean FileSettings: type: object properties: MaxFileSize: type: boolean DriverName: type: boolean Directory: type: boolean EnablePublicLink: type: boolean PublicLinkSalt: type: boolean ThumbnailWidth: type: boolean ThumbnailHeight: type: boolean PreviewWidth: type: boolean PreviewHeight: type: boolean ProfileWidth: type: boolean ProfileHeight: type: boolean InitialFont: type: boolean AmazonS3AccessKeyId: type: boolean AmazonS3SecretAccessKey: type: boolean AmazonS3Bucket: type: boolean AmazonS3Region: type: boolean AmazonS3Endpoint: type: boolean AmazonS3SSL: type: boolean EmailSettings: type: object properties: EnableSignUpWithEmail: type: boolean EnableSignInWithEmail: type: boolean EnableSignInWithUsername: type: boolean SendEmailNotifications: type: boolean RequireEmailVerification: type: boolean FeedbackName: type: boolean FeedbackEmail: type: boolean FeedbackOrganization: type: boolean SMTPUsername: type: boolean SMTPPassword: type: boolean SMTPServer: type: boolean SMTPPort: type: boolean ConnectionSecurity: type: boolean InviteSalt: type: boolean PasswordResetSalt: type: boolean SendPushNotifications: type: boolean PushNotificationServer: type: boolean PushNotificationContents: type: boolean EnableEmailBatching: type: boolean EmailBatchingBufferSize: type: boolean EmailBatchingInterval: type: boolean RateLimitSettings: type: object properties: Enable: type: boolean PerSec: type: boolean MaxBurst: type: boolean MemoryStoreSize: type: boolean VaryByRemoteAddr: type: boolean VaryByHeader: type: boolean PrivacySettings: type: object properties: ShowEmailAddress: type: boolean ShowFullName: type: boolean SupportSettings: type: object properties: TermsOfServiceLink: type: boolean PrivacyPolicyLink: type: boolean AboutLink: type: boolean HelpLink: type: boolean ReportAProblemLink: type: boolean SupportEmail: type: boolean GitLabSettings: type: object properties: Enable: type: boolean Secret: type: boolean Id: type: boolean Scope: type: boolean AuthEndpoint: type: boolean TokenEndpoint: type: boolean UserApiEndpoint: type: boolean GoogleSettings: type: object properties: Enable: type: boolean Secret: type: boolean Id: type: boolean Scope: type: boolean AuthEndpoint: type: boolean TokenEndpoint: type: boolean UserApiEndpoint: type: boolean Office365Settings: type: object properties: Enable: type: boolean Secret: type: boolean Id: type: boolean Scope: type: boolean AuthEndpoint: type: boolean TokenEndpoint: type: boolean UserApiEndpoint: type: boolean LdapSettings: type: object properties: Enable: type: boolean LdapServer: type: boolean LdapPort: type: boolean ConnectionSecurity: type: boolean BaseDN: type: boolean BindUsername: type: boolean BindPassword: type: boolean UserFilter: type: boolean FirstNameAttribute: type: boolean LastNameAttribute: type: boolean EmailAttribute: type: boolean UsernameAttribute: type: boolean NicknameAttribute: type: boolean IdAttribute: type: boolean PositionAttribute: type: boolean SyncIntervalMinutes: type: boolean SkipCertificateVerification: type: boolean QueryTimeout: type: boolean MaxPageSize: type: boolean LoginFieldName: type: boolean ComplianceSettings: type: object properties: Enable: type: boolean Directory: type: boolean EnableDaily: type: boolean LocalizationSettings: type: object properties: DefaultServerLocale: type: boolean DefaultClientLocale: type: boolean AvailableLocales: type: boolean SamlSettings: type: object properties: Enable: type: boolean Verify: type: boolean Encrypt: type: boolean IdpUrl: type: boolean IdpDescriptorUrl: type: boolean AssertionConsumerServiceURL: type: boolean IdpCertificateFile: type: boolean PublicCertificateFile: type: boolean PrivateKeyFile: type: boolean FirstNameAttribute: type: boolean LastNameAttribute: type: boolean EmailAttribute: type: boolean UsernameAttribute: type: boolean NicknameAttribute: type: boolean LocaleAttribute: type: boolean PositionAttribute: type: boolean LoginButtonText: type: boolean NativeAppSettings: type: object properties: AppDownloadLink: type: boolean AndroidAppDownloadLink: type: boolean IosAppDownloadLink: type: boolean ClusterSettings: type: object properties: Enable: type: boolean InterNodeListenAddress: type: boolean InterNodeUrls: type: boolean MetricsSettings: type: object properties: Enable: type: boolean BlockProfileRate: type: boolean ListenAddress: type: boolean AnalyticsSettings: type: object properties: MaxUsersForStatistics: type: boolean SamlCertificateStatus: type: object properties: idp_certificate_file: description: Status is good when `true` type: boolean public_certificate_file: description: Status is good when `true` type: boolean private_key_file: description: Status is good when `true` type: boolean Compliance: type: object properties: id: type: string create_at: type: integer format: int64 user_id: type: string status: type: string count: type: integer desc: type: string type: type: string start_at: type: integer format: int64 end_at: type: integer format: int64 keywords: type: string emails: type: string ClusterInfo: type: object properties: id: description: The unique ID for the node type: string version: description: The server version the node is on type: string config_hash: description: The hash of the configuartion file the node is using type: string internode_url: description: The URL used to communicate with those node from other nodes type: string hostname: description: The hostname for this node type: string last_ping: description: The time of the last ping to this node type: integer is_alive: description: Whether or not the node is alive and well type: boolean AppError: type: object properties: status_code: type: integer id: type: string message: type: string request_id: type: string Status: type: object properties: user_id: type: string status: type: string manual: type: boolean last_activity_at: type: integer format: int64 OAuthApp: type: object properties: id: type: string description: The client id of the application client_secret: type: string description: The client secret of the application name: type: string description: The name of the client application description: type: string description: A short description of the application icon_url: type: string description: A URL to an icon to display with the application callback_urls: type: array items: type: string description: A list of callback URLs for the appliation homepage: type: string description: A link to the website of the application is_trusted: type: boolean description: Set this to `true` to skip asking users for permission create_at: type: integer description: The time of registration for the application format: int64 update_at: type: integer description: The last time of update for the application format: int64 Job: type: object properties: id: type: string description: The unique id of the job type: type: string description: The type of job create_at: type: integer description: The time at which the job was created format: int64 start_at: type: integer description: The time at which the job was started format: int64 last_activity_at: type: integer description: The last time at which the job had activity format: int64 status: type: string description: The status of the job progress: type: integer description: The progress (as a percentage) of the job data: type: object description: A freeform data field containing additional information about the job UserAccessToken: type: object properties: id: type: string description: Unique identifier for the token token: type: string description: The token used for authentication user_id: type: string description: The user the token authenticates for description: type: string description: A description of the token usage UserAccessTokenSanitized: type: object properties: id: type: string description: Unique identifier for the token user_id: type: string description: The user the token authenticates for description: type: string description: A description of the token usage is_active: type: boolean description: Indicates whether the token is active GlobalDataRetentionPolicy: type: object properties: message_deletion_enabled: type: boolean description: Indicates whether data retention policy deletion of messages is enabled globally. file_deletion_enabled: type: boolean description: Indicates whether data retention policy deletion of file attachments is enabled globally. message_retention_cutoff: type: integer description: The current server timestamp before which messages should be deleted. file_retention_cutoff: type: integer description: The current server timestamp before which files should be deleted. DataRetentionPolicyWithoutId: type: object properties: display_name: type: string description: The display name for this retention policy. post_duration: type: integer description: | The number of days a message will be retained before being deleted by this policy. If this value is less than 0, the policy has infinite retention (i.e. messages are never deleted). DataRetentionPolicy: allOf: - $ref: '#/components/schemas/DataRetentionPolicyWithoutId' - type: object properties: id: type: string description: The ID of this retention policy. DataRetentionPolicyWithTeamAndChannelCounts: allOf: - $ref: '#/components/schemas/DataRetentionPolicy' - type: object properties: team_count: type: integer description: The number of teams to which this policy is applied. channel_count: type: integer description: The number of channels to which this policy is applied. DataRetentionPolicyWithTeamAndChannelIds: allOf: - $ref: '#/components/schemas/DataRetentionPolicyWithoutId' - type: object properties: team_ids: type: array items: type: string description: The IDs of the teams to which this policy should be applied. channel_ids: type: array items: type: string description: The IDs of the channels to which this policy should be applied. DataRetentionPolicyCreate: allOf: - $ref: '#/components/schemas/DataRetentionPolicyWithTeamAndChannelIds' required: - display_name - post_duration DataRetentionPolicyForTeam: type: object properties: team_id: type: string description: The team ID. post_duration: type: integer description: The number of days a message will be retained before being deleted by this policy. RetentionPolicyForTeamList: type: object properties: policies: type: array items: $ref: '#/components/schemas/DataRetentionPolicyForTeam' description: The list of team policies. total_count: type: integer description: The total number of team policies. DataRetentionPolicyForChannel: type: object properties: channel_id: type: string description: The channel ID. post_duration: type: integer description: The number of days a message will be retained before being deleted by this policy. RetentionPolicyForChannelList: type: object properties: policies: type: array items: $ref: '#/components/schemas/DataRetentionPolicyForChannel' description: The list of channel policies. total_count: type: integer description: The total number of channel policies. UserNotifyProps: type: object properties: email: type: string description: Set to "true" to enable email notifications, "false" to disable. Defaults to "true". push: type: string description: Set to "all" to receive push notifications for all activity, "mention" for mentions and direct messages only, and "none" to disable. Defaults to "mention". desktop: type: string description: Set to "all" to receive desktop notifications for all activity, "mention" for mentions and direct messages only, and "none" to disable. Defaults to "all". desktop_sound: type: string description: Set to "true" to enable sound on desktop notifications, "false" to disable. Defaults to "true". mention_keys: type: string description: A comma-separated list of words to count as mentions. Defaults to username and @username. channel: type: string description: Set to "true" to enable channel-wide notifications (@channel, @all, etc.), "false" to disable. Defaults to "true". first_name: type: string description: Set to "true" to enable mentions for first name. Defaults to "true" if a first name is set, "false" otherwise. Timezone: type: object properties: useAutomaticTimezone: type: boolean description: Set to "true" to use the browser/system timezone, "false" to set manually. Defaults to "true". manualTimezone: type: string description: Value when setting manually the timezone, i.e. "Europe/Berlin". automaticTimezone: type: string description: This value is set automatically when the "useAutomaticTimezone" is set to "true". ChannelNotifyProps: type: object properties: email: type: string description: Set to "true" to enable email notifications, "false" to disable, or "default" to use the global user notification setting. push: type: string description: Set to "all" to receive push notifications for all activity, "mention" for mentions and direct messages only, "none" to disable, or "default" to use the global user notification setting. desktop: type: string description: Set to "all" to receive desktop notifications for all activity, "mention" for mentions and direct messages only, "none" to disable, or "default" to use the global user notification setting. mark_unread: type: string description: Set to "all" to mark the channel unread for any new message, "mention" to mark unread for new mentions only. Defaults to "all". PluginManifest: type: object properties: id: type: string description: Globally unique identifier that represents the plugin. name: type: string description: Name of the plugin. description: type: string description: Description of what the plugin is and does. version: type: string description: Version number of the plugin. min_server_version: type: string description: | The minimum Mattermost server version required for the plugin. Available as server version 5.6. backend: type: object description: Deprecated in Mattermost 5.2 release. properties: executable: type: string description: Path to the executable binary. server: type: object properties: executables: type: object description: Paths to executable binaries, specifying multiple entry points for different platforms when bundled together in a single plugin. properties: linux-amd64: type: string darwin-amd64: type: string windows-amd64: type: string executable: type: string description: Path to the executable binary. webapp: type: object properties: bundle_path: type: string description: Path to the webapp JavaScript bundle. settings_schema: type: object description: Settings schema used to define the System Console UI for the plugin. MarketplacePlugin: type: object properties: homepage_url: type: string description: URL that leads to the homepage of the plugin. icon_data: type: string description: Base64 encoding of a plugin icon SVG. download_url: type: string description: URL to download the plugin. release_notes_url: type: string description: URL that leads to the release notes of the plugin. labels: type: array items: type: string description: A list of the plugin labels. signature: type: string description: Base64 encoded signature of the plugin. manifest: $ref: '#/components/schemas/PluginManifest' installed_version: type: string description: Version number of the already installed plugin, if any. PushNotification: type: object properties: ack_id: type: string platform: type: string server_id: type: string device_id: type: string post_id: type: string category: type: string sound: type: string message: type: string badge: type: number cont_ava: type: number team_id: type: string channel_id: type: string root_id: type: string channel_name: type: string type: type: string sender_id: type: string sender_name: type: string override_username: type: string override_icon_url: type: string from_webhook: type: string version: type: string is_id_loaded: type: boolean PluginStatus: type: object properties: plugin_id: type: string description: Globally unique identifier that represents the plugin. name: type: string description: Name of the plugin. description: type: string description: Description of what the plugin is and does. version: type: string description: Version number of the plugin. cluster_id: type: string description: ID of the cluster in which plugin is running plugin_path: type: string description: Path to the plugin on the server state: type: number description: State of the plugin enum: - NotRunning - Starting - Running - FailedToStart - FailedToStayRunning - Stopping PluginManifestWebapp: type: object properties: id: type: string description: Globally unique identifier that represents the plugin. version: type: string description: Version number of the plugin. webapp: type: object properties: bundle_path: type: string description: Path to the webapp JavaScript bundle. Role: type: object properties: id: type: string description: The unique identifier of the role. name: type: string description: The unique name of the role, used when assigning roles to users/groups in contexts. display_name: type: string description: The human readable name for the role. description: type: string description: A human readable description of the role. permissions: type: array items: type: string description: A list of the unique names of the permissions this role grants. scheme_managed: type: boolean description: indicates if this role is managed by a scheme (true), or is a custom stand-alone role (false). Scheme: type: object properties: id: type: string description: The unique identifier of the scheme. name: type: string description: The human readable name for the scheme. description: type: string description: A human readable description of the scheme. create_at: type: integer format: int64 description: The time at which the scheme was created. update_at: type: integer format: int64 description: The time at which the scheme was last updated. delete_at: type: integer format: int64 description: The time at which the scheme was deleted. scope: type: string description: The scope to which this scheme can be applied, either "team" or "channel". default_team_admin_role: type: string description: The id of the default team admin role for this scheme. default_team_user_role: type: string description: The id of the default team user role for this scheme. default_channel_admin_role: type: string description: The id of the default channel admin role for this scheme. default_channel_user_role: type: string description: The id of the default channel user role for this scheme. TermsOfService: type: object properties: id: type: string description: The unique identifier of the terms of service. create_at: type: integer format: int64 description: The time at which the terms of service was created. user_id: type: string description: The unique identifier of the user who created these terms of service. text: type: string description: The text of terms of service. Supports Markdown. UserTermsOfService: type: object properties: user_id: type: string description: The unique identifier of the user who performed this terms of service action. terms_of_service_id: type: string description: The unique identifier of the terms of service the action was performed on. create_at: description: The time in milliseconds that this action was performed. type: integer format: int64 PostIdToReactionsMap: type: object additionalProperties: type: array items: $ref: '#/components/schemas/Reaction' Product: type: object properties: id: type: string name: type: string description: type: string price_per_seat: type: string add_ons: type: array items: $ref: '#/components/schemas/AddOn' AddOn: type: object properties: id: type: string name: type: string display_name: type: string price_per_seat: type: string ProductLimits: type: object properties: boards: $ref: '#/components/schemas/BoardsLimits' files: $ref: '#/components/schemas/FilesLimits' integrations: $ref: '#/components/schemas/IntegrationsLimits' messages: $ref: '#/components/schemas/MessagesLimits' teams: $ref: '#/components/schemas/TeamsLimits' BoardsLimits: type: object properties: cards: type: integer nullable: true views: type: integer nullable: true FilesLimits: type: object properties: total_storage: type: integer format: int64 nullable: true IntegrationsLimits: type: object properties: enabled: type: integer nullable: true MessagesLimits: type: object properties: history: type: integer nullable: true TeamsLimits: type: object properties: active: type: integer nullable: true PaymentSetupIntent: type: object properties: id: type: string client_secret: type: string PaymentMethod: type: object properties: type: type: string last_four: type: integer exp_month: type: integer exp_year: type: integer card_brand: type: string name: type: string Address: type: object properties: city: type: string country: type: string line1: type: string line2: type: string postal_code: type: string state: type: string CloudCustomer: type: object properties: id: type: string creator_id: type: string create_at: type: integer format: int64 email: type: string name: type: string num_employees: type: string contact_first_name: type: string contact_last_name: type: string billing_address: $ref: '#/components/schemas/Address' company_address: $ref: '#/components/schemas/Address' payment_method: $ref: '#/components/schemas/PaymentMethod' Subscription: type: object properties: id: type: string customer_id: type: string product_id: type: string add_ons: type: array items: type: string start_at: type: integer format: int64 end_at: type: integer format: int64 create_at: type: integer format: int64 seats: type: integer dns: type: string SubscriptionStats: type: object properties: remaining_seats: type: integer is_paid_tier: type: string Invoice: type: object properties: id: type: string number: type: string create_at: type: integer format: int64 total: type: integer format: int64 tax: type: integer format: int64 status: type: string period_start: type: integer format: int64 period_end: type: integer format: int64 subscription_id: type: string item: type: array items: $ref: '#/components/schemas/InvoiceLineItem' InvoiceLineItem: type: object properties: price_id: type: string total: type: integer format: int64 quantity: type: integer format: int64 price_per_unit: type: integer format: int64 description: type: string metadata: type: array items: type: string Group: type: object properties: id: type: string name: type: string display_name: type: string description: type: string source: type: string remote_id: type: string create_at: type: integer format: int64 update_at: type: integer format: int64 delete_at: type: integer format: int64 has_syncables: type: boolean GroupSyncableTeam: type: object properties: team_id: type: string group_id: type: string auto_add: type: boolean create_at: type: integer format: int64 delete_at: type: integer format: int64 update_at: type: integer format: int64 GroupSyncableChannel: type: object properties: channel_id: type: string group_id: type: string auto_add: type: boolean create_at: type: integer format: int64 delete_at: type: integer format: int64 update_at: type: integer format: int64 GroupSyncableTeams: type: object properties: team_id: type: string team_display_name: type: string team_type: type: string group_id: type: string auto_add: type: boolean create_at: type: integer format: int64 delete_at: type: integer format: int64 update_at: type: integer format: int64 GroupSyncableChannels: type: object properties: channel_id: type: string channel_display_name: type: string channel_type: type: string team_id: type: string team_display_name: type: string team_type: type: string group_id: type: string auto_add: type: boolean create_at: type: integer format: int64 delete_at: type: integer format: int64 update_at: type: integer format: int64 ChannelModeration: type: object properties: name: type: string roles: $ref: '#/components/schemas/ChannelModeratedRoles' ChannelModeratedRoles: type: object properties: guests: $ref: '#/components/schemas/ChannelModeratedRole' members: $ref: '#/components/schemas/ChannelModeratedRole' ChannelModeratedRole: type: object properties: value: type: boolean enabled: type: boolean ChannelModeratedRolesPatch: type: object properties: guests: type: boolean members: type: boolean ChannelModerationPatch: type: object properties: name: type: string roles: $ref: '#/components/schemas/ChannelModeratedRolesPatch' ChannelMemberCountByGroup: description: An object describing group member information in a channel type: object properties: group_id: type: string description: ID of the group channel_member_count: type: number description: Total number of group members in the channel channel_member_timezones_count: type: number description: Total number of unique timezones for the group members in the channel LDAPGroupsPaged: description: A paged list of LDAP groups type: object properties: count: type: number description: Total number of groups groups: type: array items: $ref: '#/components/schemas/LDAPGroup' LDAPGroup: description: A LDAP group type: object properties: has_syncables: type: boolean mattermost_group_id: type: string primary_key: type: string name: type: string SidebarCategory: description: User's sidebar category type: object properties: id: type: string user_id: type: string team_id: type: string display_name: type: string type: type: string enum: - channels - custom - direct_messages - favorites SidebarCategoryWithChannels: description: User's sidebar category with it's channels type: object properties: id: type: string user_id: type: string team_id: type: string display_name: type: string type: type: string enum: - channels - custom - direct_messages - favorites channel_ids: type: array items: type: string OrderedSidebarCategories: description: List of user's categories with their channels type: object properties: order: type: array items: type: string categories: type: array items: $ref: '#/components/schemas/SidebarCategoryWithChannels' Bot: description: A bot account type: object properties: user_id: description: The user id of the associated user entry. type: string create_at: description: The time in milliseconds a bot was created type: integer format: int64 update_at: description: The time in milliseconds a bot was last updated type: integer format: int64 delete_at: description: The time in milliseconds a bot was deleted type: integer format: int64 username: type: string display_name: type: string description: type: string owner_id: description: The user id of the user that currently owns this bot. type: string Server_Busy: type: object properties: busy: description: True if the server is marked as busy (under high load) type: boolean expires: description: timestamp - number of seconds since Jan 1, 1970 UTC. type: integer format: int64 GroupWithSchemeAdmin: description: group augmented with scheme admin information type: object properties: group: $ref: '#/components/schemas/Group' scheme_admin: type: boolean GroupsAssociatedToChannels: description: a map of channel id(s) to the set of groups that constrain the corresponding channel in a team type: object additionalProperties: type: array items: $ref: '#/components/schemas/GroupWithSchemeAdmin' OrphanedRecord: description: an object containing information about an orphaned record. type: object properties: parent_id: type: string description: the id of the parent relation (table) entry. child_id: type: string description: the id of the child relation (table) entry. UserThread: description: a thread that user is following type: object properties: id: type: string description: ID of the post that is this thread's root reply_count: type: integer description: number of replies in this thread last_reply_at: type: integer format: int64 description: timestamp of the last post to this thread last_viewed_at: type: integer format: int64 description: timestamp of the last time the user viewed this thread participants: type: array description: list of users participating in this thread. only includes IDs unless 'extended' was set to 'true' items: $ref: '#/components/schemas/Post' post: $ref: '#/components/schemas/Post' RelationalIntegrityCheckData: description: an object containing the results of a relational integrity check. type: object properties: parent_name: type: string description: the name of the parent relation (table). child_name: type: string description: the name of the child relation (table). parent_id_attr: type: string description: the name of the attribute (column) containing the parent id. child_id_attr: type: string description: the name of the attribute (column) containing the child id. records: description: the list of orphaned records found. type: array items: $ref: '#/components/schemas/OrphanedRecord' IntegrityCheckResult: description: an object with the result of the integrity check. type: object properties: data: $ref: '#/components/schemas/RelationalIntegrityCheckData' err: type: string description: a string value set in case of error. UploadSession: description: an object containing information used to keep track of a file upload. type: object properties: id: description: The unique identifier for the upload. type: string type: description: The type of the upload. type: string enum: - attachment - import create_at: description: The time the upload was created in milliseconds. type: integer format: int64 user_id: description: The ID of the user performing the upload. type: string channel_id: description: The ID of the channel to upload to. type: string filename: description: The name of the file to upload. type: string file_size: description: The size of the file to upload in bytes. type: integer format: int64 file_offset: description: The amount of data uploaded in bytes. type: integer format: int64 Notice: type: object properties: id: description: Notice ID type: string sysAdminOnly: description: Does this notice apply only to sysadmins type: boolean teamAdminOnly: description: Does this notice apply only to team admins type: boolean action: description: Optional action to perform on action button click. (defaults to closing the notice) type: string actionParam: description: "Optional action parameter. \nExample: {\"action\": \"url\", actionParam: \"/console/some-page\"}" type: string actionText: description: Optional override for the action button text (defaults to OK) type: string description: description: Notice content. Use {{Mattermost}} instead of plain text to support white-labeling. Text supports Markdown. type: string image: description: URL of image to display type: string title: description: Notice title. Use {{Mattermost}} instead of plain text to support white-labeling. Text supports Markdown. type: string SharedChannel: type: object properties: id: description: Channel id of the shared channel type: string team_id: type: string home: description: Is this the home cluster for the shared channel type: boolean readonly: description: Is this shared channel shared as read only type: boolean name: description: Channel name as it is shared (may be different than original channel name) type: string display_name: description: Channel display name as it appears locally type: string purpose: type: string header: type: string creator_id: description: Id of the user that shared the channel type: string create_at: description: Time in milliseconds that the channel was shared type: integer update_at: description: Time in milliseconds that the shared channel record was last updated type: integer remote_id: description: Id of the remote cluster where the shared channel is homed type: string RemoteClusterInfo: type: object properties: display_name: description: The display name for the remote cluster type: string create_at: description: The time in milliseconds a remote cluster was created type: integer format: int64 last_ping_at: description: The time in milliseconds a remote cluster was last pinged successfully type: integer format: int64 SystemStatusResponse: type: object properties: AndroidLatestVersion: description: Latest Android version supported type: string AndroidMinVersion: description: Minimum Android version supported type: string DesktopLatestVersion: description: Latest desktop version supported type: string DesktopMinVersion: description: Minimum desktop version supported type: string IosLatestVersion: description: Latest iOS version supported type: string IosMinVersion: description: Minimum iOS version supported type: string database_status: description: Status of database ("OK" or "UNHEALTHY"). Included when get_server_status parameter set. type: string filestore_status: description: Status of filestore ("OK" or "UNHEALTHY"). Included when get_server_status parameter set. type: string status: description: Status of server ("OK" or "UNHEALTHY"). Included when get_server_status parameter set. type: string CanReceiveNotifications: description: Whether the device id provided can receive notifications ("true", "false" or "unknown"). Included when device_id parameter set. type: string UserThreads: type: object properties: total: description: Total number of threads (used for paging) type: integer threads: description: Array of threads type: array items: $ref: '#/components/schemas/UserThread' LicenseRenewalLink: type: object properties: renewal_link: description: License renewal link type: string System: type: object properties: name: description: System property name type: string value: description: System property value type: string PostsUsage: type: object properties: count: type: number description: Total no. of posts StorageUsage: type: object properties: bytes: type: number description: Total file storage usage for the instance in bytes rounded down to the most significant digit PostAcknowledgement: type: object properties: user_id: description: The ID of the user that made this acknowledgement. type: string post_id: description: The ID of the post to which this acknowledgement was made. type: string acknowledged_at: description: The time in milliseconds in which this acknowledgement was made. type: integer format: int64 AllowedIPRange: type: object properties: CIDRBlock: description: An IP address range in CIDR notation type: string Description: description: A description for the CIDRBlock type: string UserReport: type: object properties: id: type: string create_at: description: The time in milliseconds a user was created type: integer format: int64 username: type: string email: type: string display_name: type: string description: Calculated display name based on user last_login_at: description: Last time the user was logged in type: integer format: int64 last_status_at: description: Last time the user's status was updated type: integer format: int64 last_post_date: description: Last time the user made a post within the given date range type: integer format: int64 days_active: description: Total number of days a user posted within the given date range type: integer total_posts: description: Total number of posts made by a user within the given date range type: integer Installation: type: object properties: id: description: A unique identifier type: string allowed_ip_ranges: $ref: '#/components/schemas/AllowedIPRange' state: description: The current state of the installation type: string UserLimits: type: object properties: maxUsersLimit: description: The maximum number of users allowed on server type: integer format: int64 activeUserCount: description: The number of active users in the server type: integer format: int64 OutgoingOAuthConnectionGetItem: type: object properties: id: description: The unique identifier for the outgoing OAuth connection. type: string name: description: The name of the outgoing OAuth connection. type: string create_at: description: The time in milliseconds the outgoing OAuth connection was created. type: integer format: int64 update_at: description: The time in milliseconds the outgoing OAuth connection was last updated. type: integer format: int64 grant_type: description: The grant type of the outgoing OAuth connection. type: string audiences: description: The audiences of the outgoing OAuth connection. type: string OutgoingOAuthConnectionPostItem: type: object properties: name: description: The name of the outgoing OAuth connection. type: string client_id: description: The client ID of the outgoing OAuth connection. type: string client_secret: description: The client secret of the outgoing OAuth connection. type: string credentials_username: description: The username of the credentials of the outgoing OAuth connection. type: string credentials_password: description: The password of the credentials of the outgoing OAuth connection. type: string oauth_token_url: description: The OAuth token URL of the outgoing OAuth connection. type: string grant_type: description: The grant type of the outgoing OAuth connection. type: string audiences: description: The audiences of the outgoing OAuth connection. type: string PlaybookRun: type: object properties: id: type: string description: A unique, 26 characters long, alphanumeric identifier for the playbook run. example: mx3xyzdojfgyfdx8sc8of1gdme name: type: string description: The name of the playbook run. example: Server down in EU cluster description: type: string description: The description of the playbook run. example: There is one server in the EU cluster that is not responding since April 12. is_active: type: boolean description: True if the playbook run is ongoing; false if the playbook run is ended. owner_user_id: type: string description: The identifier of the user that is commanding the playbook run. example: bqnbdf8uc0a8yz4i39qrpgkvtg team_id: type: string description: The identifier of the team where the playbook run's channel is in. example: 61ji2mpflefup3cnuif80r5rde channel_id: type: string description: The identifier of the playbook run's channel. example: hwrmiyzj3kadcilh3ukfcnsbt6 create_at: type: integer format: int64 description: The playbook run creation timestamp, formatted as the number of milliseconds since the Unix epoch. example: 1606807976289 end_at: type: integer format: int64 description: The playbook run finish timestamp, formatted as the number of milliseconds since the Unix epoch. It equals 0 if the playbook run is not finished. delete_at: type: integer format: int64 description: The playbook run deletion timestamp, formatted as the number of milliseconds since the Unix epoch. It equals 0 if the playbook run is not deleted. active_stage: type: integer format: int32 description: Zero-based index of the currently active stage. example: 1 active_stage_title: type: string description: The title of the currently active stage. example: Triage issue post_id: type: string description: If the playbook run was created from a post, this field contains the identifier of such post. If not, this field is empty. example: b2ntfcrl4ujivl456ab4b3aago playbook_id: type: string description: The identifier of the playbook with from which this playbook run was created. example: 0y4a0ntte97cxvfont8y84wa7x checklists: type: array items: $ref: '#/components/schemas/Checklist' PlaybookRunMetadata: type: object properties: channel_name: type: string description: Name of the channel associated to the playbook run. example: server-down-in-eu-cluster channel_display_name: type: string description: Display name of the channel associated to the playbook run. example: Server down in EU cluster team_name: type: string description: Name of the team the playbook run is in. example: sre-staff num_members: type: integer format: int64 description: Number of users that have been members of the playbook run at any point. example: 25 total_posts: type: integer format: int64 description: Number of posts in the channel associated to the playbook run. example: 202 PlaybookRunList: type: object properties: total_count: type: integer description: The total number of playbook runs in the list, regardless of the paging. format: int32 example: 305 page_count: type: integer description: The total number of pages. This depends on the total number of playbook runs in the database and the per_page parameter sent with the request. format: int32 example: 2 has_more: type: boolean description: A boolean describing whether there are more pages after the currently returned. example: true items: type: array description: The playbook runs in this page. items: $ref: '#/components/schemas/PlaybookRun' PlaybookAutofollows: type: object properties: total_count: type: integer description: The total number of users who marked this playbook to auto-follow runs. format: int32 example: 12 items: type: array description: The user IDs of who marked this playbook to auto-follow. items: type: string OwnerInfo: type: object required: - user_id - username properties: user_id: type: string description: A unique, 26 characters long, alphanumeric identifier for the owner. example: ahz0s61gh275i7z2ag4g1ntvjm username: type: string description: Owner's username. example: aaron.medina TriggerIdReturn: type: object required: - trigger_id properties: trigger_id: type: string description: The trigger_id returned by the slash command. example: ceenjwsg6tgdzjpofxqemy1aio Playbook: type: object properties: id: type: string description: A unique, 26 characters long, alphanumeric identifier for the playbook. example: iz0g457ikesz55dhxcfa0fk9yy title: type: string description: The title of the playbook. example: Cloud PlaybookRuns description: type: string description: The description of the playbook. example: A playbook to follow when there is a playbook run regarding the availability of the cloud service. team_id: type: string description: The identifier of the team where the playbook is in. example: p03rbi6viyztysbqnkvcqyel2i create_public_playbook_run: type: boolean description: A boolean indicating whether the playbook runs created from this playbook should be public or private. example: true create_at: type: integer format: int64 description: The playbook creation timestamp, formatted as the number of milliseconds since the Unix epoch. example: 1602235338837 delete_at: type: integer format: int64 description: The playbook deletion timestamp, formatted as the number of milliseconds since the Unix epoch. It equals 0 if the playbook is not deleted. num_stages: type: integer format: int64 description: The number of stages defined in this playbook. example: 3 num_steps: type: integer format: int64 description: The total number of steps from all the stages defined in this playbook. example: 18 checklists: type: array description: The stages defined in this playbook. items: $ref: '#/components/schemas/Checklist' member_ids: description: The identifiers of all the users that are members of this playbook. type: array items: type: string description: User ID of the playbook member. example: ilh6s1j4yefbdhxhtlzt179i6m example: ilh6s1j4yefbdhxhtlzt179i6m PlaybookList: type: object properties: total_count: type: integer description: The total number of playbooks in the list, regardless of the paging. format: int32 example: 305 page_count: type: integer description: The total number of pages. This depends on the total number of playbooks in the database and the per_page parameter sent with the request. format: int32 example: 2 has_more: type: boolean description: A boolean describing whether there are more pages after the currently returned. example: true items: type: array description: The playbooks in this page. items: $ref: '#/components/schemas/Playbook' Checklist: type: object properties: id: type: string description: A unique, 26 characters long, alphanumeric identifier for the checklist. example: 6f6nsgxzoq84fqh1dnlyivgafd title: type: string description: The title of the checklist. example: Triage issue items: type: array description: The list of tasks to do. items: $ref: '#/components/schemas/ChecklistItem' ChecklistItem: type: object properties: id: type: string description: A unique, 26 characters long, alphanumeric identifier for the checklist item. example: 6f6nsgxzoq84fqh1dnlyivgafd title: type: string description: The title of the checklist item. example: Gather information from customer. state: type: string enum: - "" - in_progress - closed description: The state of the checklist item. An empty string means that the item is not done. example: closed state_modified: type: integer format: int64 description: The timestamp for the latest modification of the item's state, formatted as the number of milliseconds since the Unix epoch. It equals 0 if the item was never modified. example: 1607774621321 assignee_id: type: string description: The identifier of the user that has been assigned to complete this item. If the item has no assignee, this is an empty string. example: pisdatkjtdlkdhht2v4inxuzx1 assignee_modified: type: integer format: int64 description: The timestamp for the latest modification of the item's assignee, formatted as the number of milliseconds since the Unix epoch. It equals 0 if the item never got an assignee. example: 1608897821125 command: type: string description: The slash command associated with this item. If the item has no slash command associated, this is an empty string example: /opsgenie on-call command_last_run: type: integer format: int64 description: The timestamp for the latest execution of the item's command, formatted as the number of milliseconds since the Unix epoch. It equals 0 if the command was never executed. example: 1608552221019 description: type: string description: A detailed description of the checklist item, formatted with Markdown. example: Ask the customer for more information in [Zendesk](https://www.zendesk.com/). Error: type: object required: - error - details properties: error: type: string description: A message with the error description. example: Error retrieving the resource. details: type: string description: Further details on where and why this error happened. example: Specific details about the error, depending on the case. WebhookOnCreationPayload: allOf: - $ref: '#/components/schemas/PlaybookRun' - type: object properties: channel_url: type: string description: Absolute URL to the playbook run's channel. example: https://example.com/ad-1/channels/channel-name details_url: type: string description: Absolute URL to the playbook run's details. example: https://example.com/ad-1/playbooks/runs/playbookRunID WebhookOnStatusUpdatePayload: allOf: - $ref: '#/components/schemas/PlaybookRun' - type: object properties: channel_url: type: string description: Absolute URL to the playbook run's channel. example: https://example.com/ad-1/channels/channel-name details_url: type: string description: Absolute URL to the playbook run's details. example: https://example.com/ad-1/playbooks/runs/playbookRunID externalDocs: description: Find out more about Mattermost url: https://about.mattermost.com security: - bearerAuth: []