openapi: 3.0.0 info: description: > The Mattermost Web Services API enables Mattermost clients and third-party applications to interact with Mattermost servers. [Official JavaScript and Golang drivers](#/#official-drivers) are available to simplify API integration. By using this API, you agree to our [terms of service](https://about.mattermost.com/default-terms/). [Find out more about Mattermost](https://about.mattermost.com/) ## Contents ### Core Concepts * [Schema & Conventions](#/#schema--conventions) * [Authentication](#/#authentication) * [Rate Limiting](#/#rate-limiting) * [Error Handling](#/#error-handling) * [WebSocket](#/#websocket) * [Authentication](#/#authentication-1) * [Websocket Events](#/#websocket-events) * [Websocket API](#/#websocket-api) ### Drivers * [Official Drivers](#/#official-drivers) * [Community-built Drivers](#/#community-built-drivers) ### Community * [Support](#/#support) * [Contributing](#/#contributing) ## Schema & Conventions - All API access is through HTTP(S) requests at `your-mattermost-url/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. - For all endpoints that implement pagination via the `per_page` parameter: - Maximum items per page: 200 (requests exceeding this will be silently truncated) - Default value if a paged API requires a `per_page` parameter and it is not provided: 60 ## Authentication 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/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. ```bash 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: ```bash 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 HTTP/1.1 200 OK Content-Type: application/json Permissions-Policy: Referrer-Policy: no-referrer Token: ckh3t4knu3fzujt76o57f5jo4w Vary: Origin Vary: Accept-Encoding X-Content-Type-Options: nosniff X-Request-Id: bk3uzm335jr9tnoh4mcsybmmjr X-Version-Id: 10.6.0.13685270376.215f100adf6ccda09afcaaa84ac4bfbd.true Date: Fri, 28 Mar 2025 09:33:22 GMT Content-Length: 796 {{user object as json}} ``` Include the `Token` as part of the `Authorization` header on your future API requests with the `Bearer` method. ```bash curl -i -H 'Authorization: Bearer ckh3t4knu3fzujt76o57f5jo4w' http://localhost:8065/api/v4/users/me ``` Alternatively, include the `Token` as your `MMAUTHTOKEN` cookie value on you future API requests: ```bash curl -i -H 'Cookie: MMAUTHTOKEN=ckh3t4knu3fzujt76o57f5jo4w' 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://developers.mattermost.com/integrate/reference/personal-access-token/) 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. ```bash curl -i -H 'Authorization: Bearer 9xuqwrwgstrb3mzrxb83nb357a' http://localhost:8065/api/v4/users/me ``` ## Rate Limiting Whenever you make an HTTP request to the Mattermost API you might notice the following headers included in the response: ```http 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 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 ``` ## Error Handling All errors will return an appropriate HTTP response code along with the following JSON body: ```json { "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 } ``` ## WebSocket 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](/#/#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: ```json { "seq": 1, "action": "authentication_challenge", "data": { "token": "mattermosttokengoeshere" } } ``` If successful, you will receive a standard OK response over the WebSocket connection: ```json { "status": "OK", "seq_reply": 1 } ``` Once successfully authenticated, the server will pass a `hello` WebSocket event containing server version over the connection. ### Websocket 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: ```json { "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: ```json { "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: ```json { "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: ```json { "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). ## Drivers 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-category/mattermost-developers-tools/). ## 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, you can: - [Join the Mattermost community server](https://community.mattermost.com) to ask questions in the Developers channel - Contact us at feedback@mattermost.com [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. version: 4.0.0 title: Mattermost API tags: - 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: metrics description: Endpoints related to metrics, including the Client Performance Monitoring feature. - name: audit_logs description: Endpoints for managing audit log certificates and configuration. - name: ai description: Endpoints for interacting with AI agents and services. servers: - url: "{your-mattermost-url}" variables: your-mattermost-url: default: http://localhost:8065 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/login/sso/code-exchange: post: tags: - users summary: Exchange SSO login code for session tokens description: > Exchange a short-lived login_code for session tokens using SAML code exchange (mobile SSO flow). This endpoint is part of the mobile SSO code-exchange flow to prevent tokens from appearing in deep links. ##### Permissions No permission required. operationId: LoginSSOCodeExchange requestBody: content: application/json: schema: type: object required: - login_code - code_verifier - state properties: login_code: description: Short-lived one-time code from SSO callback type: string code_verifier: description: SAML verifier to prove code possession type: string state: description: State parameter to prevent CSRF attacks type: string description: SSO code exchange object required: true responses: "200": description: Code exchange successful content: application/json: schema: type: object properties: token: description: Session token for authentication type: string csrf: description: CSRF token for request validation type: string "400": $ref: "#/components/responses/BadRequest" "403": $ref: "#/components/responses/Forbidden" /oauth/intune: post: tags: - users summary: Login with Microsoft Intune MAM description: > Authenticate a mobile user using a Microsoft Entra ID (Azure AD) access token for Intune Mobile Application Management (MAM) protected apps. This endpoint enables authentication for mobile apps protected by Microsoft Intune MAM policies. The access token is obtained via the Microsoft Authentication Library (MSAL) and validated against the configured Azure AD tenant and Intune MAM app registration. **Authentication Flow:** 1. Mobile app acquires an Entra ID access token via MSAL with the Intune MAM scope 2. Token is sent to this endpoint for validation 3. Server validates the token signature, claims, and tenant configuration 4. User is authenticated or created based on the token claims 5. Session token is returned for subsequent API requests **User Provisioning:** - **Office365 AuthService**: Users are automatically created on first login using the `oid` (Azure AD object ID) claim as the unique identifier - **SAML AuthService**: Users must first login via web/desktop to establish their account with the `oid` (Azure AD object ID) as AuthData. Intune MAM always uses objectId for SAML users. For Entra ID Domain Services LDAP sync, configure LdapSettings.IdAttribute to `msDS-aadObjectId` to ensure consistency. **Error Handling:** This endpoint returns specific HTTP status codes to help mobile apps handle different error scenarios: - `428 Precondition Required`: SAML user needs to login via web/desktop first - `403 Forbidden`: Configuration issues or bot accounts - `409 Conflict`: User account is deactivated - `401 Unauthorized`: Token has expired - `400 Bad Request`: Invalid token format, claims, or configuration ##### Permissions No permission required. Authentication is performed via the Entra ID access token. ##### Enterprise Feature Requires Mattermost Enterprise Advanced license and proper Intune MAM configuration (tenant ID, client ID, and auth service). operationId: LoginIntune requestBody: content: application/json: schema: $ref: "#/components/schemas/IntuneLoginRequest" description: Intune login credentials containing the Entra ID access token required: true responses: "200": description: User authentication successful content: application/json: schema: $ref: "#/components/schemas/User" "400": description: > Bad request - Invalid token format, signature, claims, or configuration. Common causes include: invalid JSON body, missing access_token, malformed JWT, invalid token issuer/audience/tenant, missing required claims (oid, email), or empty auth data after extraction. content: application/json: schema: $ref: "#/components/schemas/AppError" "401": description: Unauthorized - The Entra ID access token has expired content: application/json: schema: $ref: "#/components/schemas/AppError" "403": description: > Forbidden - Access denied. Common causes include: Intune MAM not properly configured or enabled, or user is a bot account (bots cannot use Intune login). content: application/json: schema: $ref: "#/components/schemas/AppError" "409": description: Conflict - User account has been deactivated (DeleteAt != 0) content: application/json: schema: $ref: "#/components/schemas/AppError" "428": description: > Precondition Required - SAML user account not found. The user must first login via web or desktop application to establish their Mattermost account with objectId as AuthData before using mobile Intune MAM authentication. For Entra ID Domain Services LDAP sync, ensure SamlSettings.IdAttribute references the objectidentifier claim and LdapSettings.IdAttribute is set to 'msDS-aadObjectId'. content: application/json: schema: $ref: "#/components/schemas/AppError" "500": description: > Internal Server Error - Server-side error. Common causes include: failed to initialize JWKS (JSON Web Key Set) from Microsoft's OpenID configuration, or failed to create user session. content: application/json: schema: $ref: "#/components/schemas/AppError" "501": description: > Not Implemented - Intune MAM feature is not available. This occurs when running Mattermost Team Edition or when enterprise features are not loaded. content: application/json: schema: $ref: "#/components/schemas/AppError" /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 required: false schema: type: string - name: iid in: query description: Token id from an invitation link required: false 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 position: type: string timezone: $ref: "#/components/schemas/Timezone" 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. Some fields, like `email_verified` and `notify_props`, are only visible for the authorized user or if the authorized user has the `manage_system` permission. ##### 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. 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" 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: type: array $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 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 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: Activate or deactivate a user description: > Activate or deactivate a user's account. A deactivated user can't log into Mattermost or use it without being reactivated. __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 activate the user or `false` to deactivate them required: true responses: "200": description: User activation/deactivation 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 required: false 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 and extra props to the session object description: > Attach extra props to the session object of the currently logged in session. Adding a mobile device id will enable push notifications for a user, if configured by the server. Other props are also available, like whether the device has notifications disabled and the mobile version. ##### Permissions Must be authenticated. operationId: AttachDeviceExtraProps requestBody: content: application/json: schema: type: object properties: device_id: description: Mobile device id. For Android prefix the id with `android:` and Apple with `apple:` type: string deviceNotificationDisabled: description: Whether the mobile device has notifications disabled. Accepted values are "true" or "false". type: string mobileVersion: description: Mobile app version. The version must be parseable as a semver. 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/login/type: post: tags: - users summary: Get login authentication type description: > Get the authentication service type (auth_service) for a user to determine how they should authenticate. This endpoint is typically used in the login flow to determine which authentication method to use. For this version, the endpoint only returns a non-empty `auth_service` if the user has magic_link enabled. For all other authentication methods (email/password, OAuth, SAML, LDAP), an empty string is returned. ##### Permissions No permission required operationId: GetLoginType requestBody: content: application/json: schema: type: object properties: id: description: The user ID (optional, can be used with login_id) type: string login_id: description: The login ID (email, username, or unique identifier) type: string device_id: description: The device ID for audit logging purposes type: string description: Login type request object required: true responses: "200": description: Login type retrieved successfully content: application/json: schema: type: object properties: auth_service: description: The authentication service type. Returns the actual service type if guest_magic_link is enabled (in which case a magic link is also sent to the user's email). Returns an empty string for all other authentication methods. type: string "400": $ref: "#/components/responses/BadRequest" "/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 perPage. required: false schema: type: integer - name: per_page in: query description: The size of the returned chunk of results. schema: type: integer default: 60 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. required: false schema: type: integer - name: deleted in: query description: Deleted will specify that even deleted threads should be returned (For mobile sync). required: false schema: type: boolean default: false - name: extended in: query description: Extended will enrich the response with participant details. required: false schema: type: boolean default: false - name: page in: query description: Page specifies which part of the results to return, by per_page. required: false schema: type: integer default: 0 - name: per_page in: query description: The size of the returned chunk of results. schema: type: integer default: 60 - name: totalsOnly in: query description: Setting this to true will only return the total counts. required: false schema: type: boolean default: false - name: threadsOnly in: query description: Setting this to true will only return threads. required: false 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. 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. 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. 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}/reset_failed_attempts": post: tags: - users summary: Reset the failed password attempts for a user description: | Reset the FailedAttempts field for a user to 0. This will only work for ldap and email/password users. ##### Permissions Requires `sysconsole_write_user_management_users` permission. operationId: resetPasswordFailedAttempts 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}/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. required: false 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 - name: sort in: query description: To sort by Username, set to 'Username', otherwise sort is by 'UserID' schema: type: string default: "" - name: exclude_deleted_users in: query description: Excludes deleted users from the results schema: type: boolean default: false 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": {...}}]`' required: false 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 required: false 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" /api/v4/channels/direct: post: tags: - channels summary: Create a direct message channel description: > Create a new direct message channel between two users. ##### Permissions Must be one of the two users and have `create_direct_channel` permission. Having the `manage_system` permission voids the previous requirements. operationId: CreateDirectChannel requestBody: content: application/json: schema: type: array items: type: string minItems: 2 maxItems: 2 description: The two user ids to be in the direct message required: true responses: "201": description: Direct channel creation successful content: application/json: schema: $ref: "#/components/schemas/Channel" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" /api/v4/channels/group: post: tags: - channels summary: Create a group message channel description: > Create a new group message channel to group of users. If the logged in user's id is not included in the list, it will be appended to the end. ##### Permissions Must have `create_group_channel` permission. operationId: CreateGroupChannel requestBody: content: application/json: schema: type: array items: type: string minItems: 3 maxItems: 8 description: User ids to be in the group message channel. required: true responses: "201": description: Group channel creation successful content: application/json: schema: $ref: "#/components/schemas/Channel" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" /api/v4/channels/search: post: tags: - channels summary: Search all private and open type channels across all teams description: > Returns all private and open type channels where 'term' matches on the name, display name, or purpose of the channel. Configured 'default' channels (ex Town Square and Off-Topic) can be excluded from the results with the `exclude_default_channels` boolean parameter. Channels that are associated (via GroupChannel records) to a given group can be excluded from the results with the `not_associated_to_group` parameter and a group id string. operationId: SearchAllChannels parameters: - name: system_console in: query description: > Is the request from system_console. If this is set to true, it filters channels by the logged in user. required: false schema: type: boolean default: true requestBody: content: application/json: schema: type: object required: - term properties: term: type: string description: The string to search in the channel name, display name, and purpose. not_associated_to_group: type: string description: A group id to exclude channels that are associated to that group via GroupChannel records. exclude_default_channels: type: boolean description: Exclude default channels from the results by setting this parameter to true. team_ids: type: array items: type: string description: > Filters results to channels belonging to the given team ids __Minimum server version__: 5.26 group_constrained: type: boolean description: > Filters results to only return channels constrained to a group __Minimum server version__: 5.26 exclude_group_constrained: type: boolean description: > Filters results to exclude channels constrained to a group __Minimum server version__: 5.26 public: type: boolean description: > Filters results to only return Public / Open channels, can be used in conjunction with `private` to return both `public` and `private` channels __Minimum server version__: 5.26 private: type: boolean description: > Filters results to only return Private channels, can be used in conjunction with `public` to return both `private` and `public` channels __Minimum server version__: 5.26 deleted: type: boolean description: > Filters results to only return deleted / archived channels __Minimum server version__: 5.26 page: type: string description: The page number to return, if paginated. If this parameter is not present with the `per_page` parameter then the results will be returned un-paged. per_page: type: string description: The number of entries to return per page, if paginated. If this parameter is not present with the `page` parameter then the results will be returned un-paged. exclude_policy_constrained: type: boolean default: false description: > If set to true, only channels which do not have a granular retention policy assigned to them will be returned. The `sysconsole_read_compliance_data_retention` permission is required to use this parameter. __Minimum server version__: 5.35 include_search_by_id: type: boolean default: false description: > If set to true, returns channels where given search 'term' matches channel ID. __Minimum server version__: 5.35 exclude_remote: type: boolean default: false description: > If set to true, only returns channels that are local to this server. __Minimum server version__: 10.2 description: The search terms and logic to use in the search. required: true responses: "200": description: Paginated channel response. (Note that the non-paginated response—returned if the request body does not contain both `page` and `per_page` fields—is a simple array of channels.) content: application/json: schema: type: object properties: channels: type: array description: The channels that matched the query. items: $ref: "#/components/schemas/Channel" total_count: type: number description: The total number of results, regardless of page and per_page requested. "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" /api/v4/channels/group/search: post: tags: - channels summary: Search Group Channels description: > Get a list of group channels for a user which members' usernames match the search term. __Minimum server version__: 5.14 operationId: SearchGroupChannels requestBody: content: application/json: schema: type: object required: - term properties: term: description: The search term to match against the members' usernames of the group channels type: string description: Search criteria required: true responses: "200": description: Channels search successful content: application/json: schema: type: array items: $ref: "#/components/schemas/Channel" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "/api/v4/teams/{team_id}/channels/ids": post: tags: - channels summary: Get a list of channels by ids description: | Get a list of public channels on a team by id. ##### Permissions `view_team` for the team the channels are on. operationId: GetPublicChannelsByIdsForTeam parameters: - name: team_id in: path description: Team GUID required: true schema: type: string requestBody: content: application/json: schema: type: array items: type: string description: List of channel ids. required: true responses: "200": description: Channel list retrieval successful content: application/json: schema: type: array items: $ref: "#/components/schemas/Channel" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "/api/v4/channels/{channel_id}/timezones": get: tags: - channels summary: Get timezones in a channel description: | Get a list of timezones for the users who are in this channel. __Minimum server version__: 5.6 ##### Permissions Must have the `read_channel` permission. operationId: GetChannelMembersTimezones parameters: - name: channel_id in: path description: Channel GUID required: true schema: type: string responses: "200": description: Timezone retrieval successful content: application/json: schema: type: array items: type: string "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "/api/v4/channels/{channel_id}": get: tags: - channels summary: Get a channel description: | Get channel from the provided channel id string. ##### Permissions `read_channel` permission for the channel. operationId: GetChannel parameters: - name: channel_id in: path description: Channel GUID required: true schema: type: string responses: "200": description: Channel retrieval successful content: application/json: schema: $ref: "#/components/schemas/Channel" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" put: tags: - channels summary: Update a channel description: > Update a channel. The fields that can be updated are listed as parameters. Omitted fields will be treated as blanks. ##### Permissions If updating a public channel, `manage_public_channel_members` permission is required. If updating a private channel, `manage_private_channel_members` permission is required. operationId: UpdateChannel parameters: - name: channel_id in: path description: Channel GUID required: true schema: type: string requestBody: content: application/json: schema: type: object required: - id properties: id: type: string description: The channel's id, not updatable name: type: string description: The unique handle for the channel, will be present in the channel URL display_name: type: string description: The non-unique UI name for the channel purpose: type: string description: A short description of the purpose of the channel header: type: string description: Markdown-formatted text to display in the header of the channel description: Channel object to be updated required: true responses: "200": description: Channel update successful content: application/json: schema: $ref: "#/components/schemas/Channel" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" delete: tags: - channels summary: Delete a channel description: > Archives a channel. This will set the `deleteAt` to the current timestamp in the database. Soft deleted channels may not be accessible in the user interface. They can be viewed and unarchived in the **System Console > User Management > Channels** based on your license. Direct and group message channels cannot be deleted. As of server version 5.28, optionally use the `permanent=true` query parameter to permanently delete the channel for compliance reasons. To use this feature `ServiceSettings.EnableAPIChannelDeletion` must be set to `true` in the server's configuration. If you permanently delete a channel this action is not recoverable outside of a database backup. ##### Permissions `delete_public_channel` permission if the channel is public, `delete_private_channel` permission if the channel is private, or have `manage_system` permission. operationId: DeleteChannel parameters: - name: channel_id in: path description: Channel GUID required: true schema: type: string responses: "200": description: Channel deletion successful content: application/json: schema: $ref: "#/components/schemas/StatusOK" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "/api/v4/channels/{channel_id}/patch": put: tags: - channels summary: Patch a channel description: > Partially update a channel by providing only the fields you want to update. Omitted fields will not be updated. 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 banner_info: $ref: "#/components/schemas/ChannelBanner" 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" "/api/v4/channels/{channel_id}/pinned": get: tags: - channels summary: Get a channel's pinned posts description: Get a list of pinned posts for channel. operationId: GetPinnedPosts parameters: - name: channel_id in: path description: Channel GUID required: true schema: type: string responses: "200": description: The list of channel pinned posts content: application/json: schema: $ref: "#/components/schemas/PostList" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "/api/v4/teams/{team_id}/channels": get: tags: - channels summary: Get public channels description: > Get a page of public channels on a team based on query string parameters - page and per_page. ##### Permissions Must be authenticated and have the `list_team_channels` permission. operationId: GetPublicChannelsForTeam parameters: - name: team_id in: path description: Team GUID required: true schema: type: string - name: page in: query description: The page to select. schema: type: integer default: 0 - name: per_page in: query description: The number of public channels per page. schema: type: integer default: 60 responses: "200": description: Channels retrieval successful content: application/json: schema: type: array items: $ref: "#/components/schemas/Channel" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "/api/v4/teams/{team_id}/channels/private": get: tags: - channels summary: Get private channels description: | Get a page of private channels on a team based on query string parameters - team_id, page and per_page. __Minimum server version__: 5.26 ##### Permissions Must have `manage_system` permission. operationId: GetPrivateChannelsForTeam parameters: - name: team_id in: path description: Team GUID required: true schema: type: string - name: page in: query description: The page to select. schema: type: integer default: 0 - name: per_page in: query description: The number of private channels per page. schema: type: integer default: 60 responses: "200": description: Channels retrieval successful content: application/json: schema: type: array items: $ref: "#/components/schemas/Channel" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "/api/v4/teams/{team_id}/channels/deleted": get: tags: - channels summary: Get deleted channels description: > Get a page of deleted channels on a team based on query string parameters - team_id, page and per_page. __Minimum server version__: 3.10 operationId: GetDeletedChannelsForTeam parameters: - name: team_id in: path description: Team GUID required: true schema: type: string - name: page in: query description: The page to select. schema: type: integer default: 0 - name: per_page in: query description: The number of public channels per page. schema: type: integer default: 60 responses: "200": description: Channels retrieval successful content: application/json: schema: type: array items: $ref: "#/components/schemas/Channel" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "/api/v4/teams/{team_id}/channels/autocomplete": get: tags: - channels summary: Autocomplete channels description: > Autocomplete public channels on a team based on the search term provided in the request URL. __Minimum server version__: 4.7 ##### Permissions Must have the `list_team_channels` permission. operationId: AutocompleteChannelsForTeam parameters: - name: team_id in: path description: Team GUID required: true schema: type: string - name: name in: query description: Name or display name required: true schema: type: string responses: "200": description: Channels autocomplete successful content: application/json: schema: type: array items: $ref: "#/components/schemas/Channel" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "/api/v4/teams/{team_id}/channels/search_autocomplete": get: tags: - channels summary: Autocomplete channels for search description: > Autocomplete your channels on a team based on the search term provided in the request URL. __Minimum server version__: 5.4 ##### Permissions Must have the `list_team_channels` permission. operationId: AutocompleteChannelsForTeamForSearch parameters: - name: team_id in: path description: Team GUID required: true schema: type: string - name: name in: query description: Name or display name required: true schema: type: string responses: "200": description: Channels autocomplete successful content: application/json: schema: type: array items: $ref: "#/components/schemas/Channel" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "/api/v4/teams/{team_id}/channels/search": post: tags: - channels summary: Search channels description: > Search public channels on a team based on the search term provided in the request body. ##### Permissions Must have the `list_team_channels` permission. In server version 5.16 and later, a user without the `list_team_channels` permission will be able to use this endpoint, with the search results limited to the channels that the user is a member of. operationId: SearchChannels parameters: - name: team_id in: path description: Team GUID required: true schema: type: string requestBody: content: application/json: schema: type: object required: - term properties: term: description: The search term to match against the name or display name of channels type: string description: Search criteria required: true responses: "201": description: Channels search successful content: application/json: schema: type: array items: $ref: "#/components/schemas/Channel" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "/api/v4/teams/{team_id}/channels/name/{channel_name}": get: tags: - channels summary: Get a channel by name description: | Gets channel from the provided team id and channel name strings. ##### Permissions `read_channel` permission for the channel. operationId: GetChannelByName parameters: - name: team_id in: path description: Team GUID required: true schema: type: string - name: channel_name in: path description: Channel Name required: true schema: type: string - name: include_deleted in: query description: Defines if deleted channels should be returned or not (Mattermost Server 5.26.0+) schema: type: boolean default: false responses: "200": description: Channel retrieval successful content: application/json: schema: $ref: "#/components/schemas/Channel" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "/api/v4/teams/name/{team_name}/channels/name/{channel_name}": get: tags: - channels summary: Get a channel by name and team name description: | Gets a channel from the provided team name and channel name strings. ##### Permissions `read_channel` permission for the channel. operationId: GetChannelByNameForTeamName parameters: - name: team_name in: path description: Team Name required: true schema: type: string - name: channel_name in: path description: Channel Name required: true schema: type: string - name: include_deleted in: query description: Defines if deleted channels should be returned or not (Mattermost Server 5.26.0+) schema: type: boolean default: false responses: "200": description: Channel retrieval successful content: application/json: schema: $ref: "#/components/schemas/Channel" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "/api/v4/channels/{channel_id}/members": get: tags: - channels summary: Get channel members description: | Get a page of members for a channel. ##### Permissions `read_channel` permission for the channel. operationId: GetChannelMembers parameters: - name: channel_id in: path description: Channel GUID required: true schema: type: string - name: page in: query description: The page to select. schema: type: integer default: 0 - name: per_page in: query description: The number of members per page. schema: type: integer default: 60 responses: "200": description: Channel members retrieval successful content: application/json: schema: type: array items: $ref: "#/components/schemas/ChannelMember" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" post: tags: - channels summary: Add user(s) to channel description: Add a user(s) to a channel by creating a channel member object(s). operationId: AddChannelMember parameters: - name: channel_id in: path description: The channel ID required: true schema: type: string requestBody: content: application/json: schema: type: object properties: user_id: type: string description: The ID of user to add into the channel, for backwards compatibility. user_ids: type: array items: type: string minItems: 1 maxItems: 1000 description: The IDs of users to add into the channel, required if 'user_id' doess not exist. post_root_id: type: string description: The ID of root post where link to add channel member originates required: true responses: "201": description: Channel member creation successful content: application/json: schema: $ref: "#/components/schemas/ChannelMember" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "/api/v4/channels/{channel_id}/members/ids": post: tags: - channels summary: Get channel members by ids description: | Get a list of channel members based on the provided user ids. ##### Permissions Must have the `read_channel` permission. operationId: GetChannelMembersByIds parameters: - name: channel_id in: path description: Channel GUID required: true schema: type: string requestBody: content: application/json: schema: type: array items: type: string description: List of user ids. required: true responses: "200": description: Channel member list retrieval successful content: application/json: schema: type: array items: $ref: "#/components/schemas/ChannelMember" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "/api/v4/channels/{channel_id}/members/{user_id}": get: tags: - channels summary: Get channel member description: | Get a channel member. ##### Permissions `read_channel` permission for the channel. operationId: GetChannelMember parameters: - name: channel_id in: path description: Channel GUID required: true schema: type: string - name: user_id in: path description: User GUID required: true schema: type: string responses: "200": description: Channel member retrieval successful content: application/json: schema: $ref: "#/components/schemas/ChannelMember" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" delete: tags: - channels summary: Remove user from channel description: > Delete a channel member, effectively removing them from a channel. In server version 5.3 and later, channel members can only be deleted from public or private channels. ##### Permissions `manage_public_channel_members` permission if the channel is public. `manage_private_channel_members` permission if the channel is private. operationId: RemoveUserFromChannel parameters: - name: channel_id in: path description: Channel GUID required: true schema: type: string - name: user_id in: path description: User GUID required: true schema: type: string responses: "200": description: Channel member deletion successful content: application/json: schema: $ref: "#/components/schemas/StatusOK" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "/api/v4/channels/{channel_id}/members/{user_id}/roles": put: tags: - channels summary: Update channel roles description: | Update a user's roles for a channel. ##### Permissions Must have `manage_channel_roles` permission for the channel. operationId: UpdateChannelRoles parameters: - name: channel_id in: path description: Channel GUID required: true schema: type: string - name: user_id in: path description: User GUID required: true schema: type: string requestBody: content: application/json: schema: type: object required: - roles properties: roles: type: string description: Space-delimited channel roles to assign to the user required: true responses: "200": description: Channel roles update successful content: application/json: schema: $ref: "#/components/schemas/StatusOK" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "/api/v4/channels/{channel_id}/members/{user_id}/schemeRoles": put: tags: - channels summary: Update the scheme-derived roles of a channel member. description: > Update a channel member's scheme_admin/scheme_user properties. Typically this should either be `scheme_admin=false, scheme_user=true` for ordinary channel member, or `scheme_admin=true, scheme_user=true` for a channel admin. __Minimum server version__: 5.0 ##### Permissions Must be authenticated and have the `manage_channel_roles` permission. operationId: UpdateChannelMemberSchemeRoles parameters: - name: channel_id in: path description: Channel GUID required: true schema: type: string - name: user_id in: path description: User GUID required: true schema: type: string requestBody: content: application/json: schema: type: object required: - scheme_admin - scheme_user properties: scheme_admin: type: boolean scheme_user: type: boolean description: Scheme properties. required: true responses: "200": description: Channel member's scheme-derived roles updated successfully. content: application/json: schema: $ref: "#/components/schemas/StatusOK" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "/api/v4/channels/{channel_id}/members/{user_id}/notify_props": put: tags: - channels summary: Update channel notifications description: > Update a user's notification properties for a channel. Only the provided fields are updated. ##### Permissions Must be logged in as the user or have `edit_other_users` permission. operationId: UpdateChannelNotifyProps parameters: - name: channel_id in: path description: Channel GUID required: true schema: type: string - name: user_id in: path description: User GUID required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/ChannelNotifyProps" required: true responses: "200": description: Channel notification properties update successful content: application/json: schema: $ref: "#/components/schemas/StatusOK" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "/api/v4/channels/members/{user_id}/view": post: tags: - channels summary: View channel description: > Perform all the actions involved in viewing a channel. This includes marking channels as read, clearing push notifications, and updating the active channel. ##### Permissions Must be logged in as user or have `edit_other_users` permission. __Response only includes `last_viewed_at_times` in Mattermost server 4.3 and newer.__ operationId: ViewChannel parameters: - in: path name: user_id description: User ID to perform the view action for required: true schema: type: string requestBody: content: application/json: schema: type: object required: - channel_id properties: channel_id: type: string description: The channel ID that is being viewed. Use a blank string to indicate that all channels have lost focus. prev_channel_id: type: string description: The channel ID of the previous channel, used when switching channels. Providing this ID will cause push notifications to clear on the channel being switched to. description: Paremeters affecting how and which channels to view required: true responses: "200": description: Channel view successful content: application/json: schema: type: object properties: status: type: string description: Value should be "OK" if successful last_viewed_at_times: type: object description: A JSON object mapping channel IDs to the channel view times "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "/api/v4/users/{user_id}/teams/{team_id}/channels/members": get: tags: - channels summary: Get channel memberships and roles for a user description: > Get all channel memberships and associated membership roles (i.e. `channel_user`, `channel_admin`) for a user on a specific team. ##### Permissions Logged in as the user and `view_team` permission for the team. Having `manage_system` permission voids the previous requirements. operationId: GetChannelMembersForUser parameters: - name: user_id in: path description: User GUID required: true schema: type: string - name: team_id in: path description: Team GUID required: true schema: type: string responses: "200": description: Channel members retrieval successful content: application/json: schema: type: array items: $ref: "#/components/schemas/ChannelMember" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "/api/v4/users/{user_id}/teams/{team_id}/channels": get: tags: - channels summary: Get channels for user description: > Get all the channels on a team for a user. ##### Permissions Logged in as the user, or have `edit_other_users` permission, and `view_team` permission for the team. operationId: GetChannelsForTeamForUser parameters: - name: user_id in: path description: User GUID required: true schema: type: string - name: team_id in: path description: Team GUID required: true schema: type: string - name: include_deleted in: query description: Defines if deleted channels should be returned or not schema: type: boolean default: false - name: last_delete_at in: query description: Filters the deleted channels by this time in epoch format. Does not have any effect if include_deleted is set to false. schema: type: integer default: 0 responses: "200": description: Channels retrieval successful content: application/json: schema: type: array items: $ref: "#/components/schemas/Channel" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "/api/v4/users/{user_id}/channels": get: tags: - channels summary: Get all channels from all teams description: | Get all channels from all teams that a user is a member of. __Minimum server version__: 6.1 ##### Permissions Logged in as the user, or have `edit_other_users` permission. operationId: GetChannelsForUser parameters: - name: user_id in: path description: The ID of the user. This can also be "me" which will point to the current user. required: true schema: type: string - name: last_delete_at in: query description: Filters the deleted channels by this time in epoch format. Does not have any effect if include_deleted is set to false. schema: type: integer default: 0 - name: include_deleted in: query description: Defines if deleted channels should be returned or not schema: type: boolean default: false responses: "200": description: Channels retrieval successful content: application/json: schema: type: array items: $ref: "#/components/schemas/Channel" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "/api/v4/users/{user_id}/channels/{channel_id}/unread": get: tags: - channels summary: Get unread messages description: > Get the total unread messages and mentions for a channel for a user. ##### Permissions Must be logged in as user and have the `read_channel` permission, or have `edit_other_usrs` permission. operationId: GetChannelUnread parameters: - name: user_id in: path description: User GUID required: true schema: type: string - name: channel_id in: path description: Channel GUID required: true schema: type: string responses: "200": description: Channel unreads retrieval successful content: application/json: schema: $ref: "#/components/schemas/ChannelUnread" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "/api/v4/channels/{channel_id}/scheme": put: tags: - channels summary: Set a channel's scheme description: > Set a channel's scheme, more specifically sets the scheme_id value of a channel record. ##### Permissions Must have `manage_system` permission. __Minimum server version__: 4.10 operationId: UpdateChannelScheme parameters: - name: channel_id in: path description: Channel GUID required: true schema: type: string requestBody: content: application/json: schema: type: object required: - scheme_id properties: scheme_id: type: string description: The ID of the scheme. description: Scheme GUID required: true responses: "200": description: Update channel scheme successful content: application/json: schema: $ref: "#/components/schemas/StatusOK" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "501": $ref: "#/components/responses/NotImplemented" "/api/v4/channels/{channel_id}/members_minus_group_members": get: tags: - channels summary: Channel members minus group members. description: > Get the set of users who are members of the channel minus the set of users who are members of the given groups. Each user object contains an array of group objects representing the group memberships for that user. Each user object contains the boolean fields `scheme_guest`, `scheme_user`, and `scheme_admin` representing the roles that user has for the given channel. ##### Permissions Must have `manage_system` permission. __Minimum server version__: 5.14 operationId: ChannelMembersMinusGroupMembers parameters: - name: channel_id in: path description: Channel GUID required: true schema: type: string - name: group_ids in: query description: A comma-separated list of group ids. required: true schema: type: string default: "" - name: page in: query description: The page to select. schema: type: integer default: 0 - name: per_page in: query description: The number of users per page. schema: type: integer default: 0 responses: "200": description: Successfully returns users specified by the pagination, and the total_count. "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "/api/v4/channels/{channel_id}/member_counts_by_group": get: tags: - channels summary: Channel members counts for each group that has atleast one member in the channel description: > Returns a set of ChannelMemberCountByGroup objects which contain a `group_id`, `channel_member_count` and a `channel_member_timezones_count`. ##### Permissions Must have `read_channel` permission for the given channel. __Minimum server version__: 5.24 operationId: GetChannelMemberCountsByGroup parameters: - name: channel_id in: path description: Channel GUID required: true schema: type: string - name: include_timezones in: query description: Defines if member timezone counts should be returned or not schema: type: boolean default: false responses: "200": description: Successfully returns member counts by group for the given channel. "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "/api/v4/channels/{channel_id}/moderations": get: tags: - channels summary: Get information about channel's moderation. description: > ##### Permissions Must have `manage_system` permission. __Minimum server version__: 5.22 operationId: GetChannelModerations parameters: - name: channel_id in: path description: Channel GUID required: true schema: type: string responses: "200": description: "Retreived successfully" content: application/json: schema: type: array items: $ref: "#/components/schemas/ChannelModeration" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "/api/v4/channels/{channel_id}/moderations/patch": put: tags: - channels summary: Update a channel's moderation settings. description: > ##### Permissions Must have `manage_system` permission. __Minimum server version__: 5.22 operationId: PatchChannelModerations requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ChannelModerationPatch" parameters: - name: channel_id in: path description: Channel GUID required: true schema: type: string responses: "200": description: "Patched successfully" content: application/json: schema: type: array items: $ref: "#/components/schemas/ChannelModeration" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "/api/v4/users/{user_id}/teams/{team_id}/channels/categories": get: tags: - channels summary: Get user's sidebar categories description: > Get a list of sidebar categories that will appear in the user's sidebar on the given team, including a list of channel IDs in each category. __Minimum server version__: 5.26 ##### Permissions Must be authenticated and have the `list_team_channels` permission. operationId: GetSidebarCategoriesForTeamForUser parameters: - name: team_id in: path description: Team GUID required: true schema: type: string - name: user_id in: path description: User GUID required: true schema: type: string responses: "200": description: Category retrieval successful content: application/json: schema: type: array items: $ref: "#/components/schemas/OrderedSidebarCategories" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" post: tags: - channels summary: Create user's sidebar category description: > Create a custom sidebar category for the user on the given team. __Minimum server version__: 5.26 ##### Permissions Must be authenticated and have the `list_team_channels` permission. operationId: CreateSidebarCategoryForTeamForUser parameters: - name: team_id in: path description: Team GUID required: true schema: type: string - name: user_id in: path description: User GUID required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/SidebarCategory" required: true responses: "200": description: Category creation successful content: application/json: schema: $ref: "#/components/schemas/SidebarCategory" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" put: tags: - channels summary: Update user's sidebar categories description: > Update any number of sidebar categories for the user on the given team. This can be used to reorder the channels in these categories. __Minimum server version__: 5.26 ##### Permissions Must be authenticated and have the `list_team_channels` permission. operationId: UpdateSidebarCategoriesForTeamForUser parameters: - name: team_id in: path description: Team GUID required: true schema: type: string - name: user_id in: path description: User GUID required: true schema: type: string requestBody: content: application/json: schema: type: array items: $ref: "#/components/schemas/SidebarCategory" required: true responses: "200": description: Category update successful content: application/json: schema: $ref: "#/components/schemas/SidebarCategory" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "/api/v4/users/{user_id}/teams/{team_id}/channels/categories/order": get: tags: - channels summary: Get user's sidebar category order description: > Returns the order of the sidebar categories for a user on the given team as an array of IDs. __Minimum server version__: 5.26 ##### Permissions Must be authenticated and have the `list_team_channels` permission. operationId: GetSidebarCategoryOrderForTeamForUser parameters: - name: team_id in: path description: Team GUID required: true schema: type: string - name: user_id in: path description: User GUID required: true schema: type: string responses: "200": description: Order retrieval successful content: application/json: schema: type: array items: type: string "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" put: tags: - channels summary: Update user's sidebar category order description: > Updates the order of the sidebar categories for a user on the given team. The provided array must include the IDs of all categories on the team. __Minimum server version__: 5.26 ##### Permissions Must be authenticated and have the `list_team_channels` permission. operationId: UpdateSidebarCategoryOrderForTeamForUser parameters: - name: team_id in: path description: Team GUID required: true schema: type: string - name: user_id in: path description: User GUID required: true schema: type: string requestBody: content: application/json: schema: type: array items: type: string required: true responses: "200": description: Order update successful content: application/json: schema: type: array items: type: string "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "/api/v4/users/{user_id}/teams/{team_id}/channels/categories/{category_id}": get: tags: - channels summary: Get sidebar category description: > Returns a single sidebar category for the user on the given team. __Minimum server version__: 5.26 ##### Permissions Must be authenticated and have the `list_team_channels` permission. operationId: GetSidebarCategoryForTeamForUser parameters: - name: team_id in: path description: Team GUID required: true schema: type: string - name: user_id in: path description: User GUID required: true schema: type: string - name: category_id in: path description: Category GUID required: true schema: type: string responses: "200": description: Category retrieval successful content: application/json: schema: $ref: "#/components/schemas/SidebarCategory" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" put: tags: - channels summary: Update sidebar category description: > Updates a single sidebar category for the user on the given team. __Minimum server version__: 5.26 ##### Permissions Must be authenticated and have the `list_team_channels` permission. operationId: UpdateSidebarCategoryForTeamForUser parameters: - name: team_id in: path description: Team GUID required: true schema: type: string - name: user_id in: path description: User GUID required: true schema: type: string - name: category_id in: path description: Category GUID required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/SidebarCategory" required: true responses: "200": description: Category update successful content: application/json: schema: $ref: "#/components/schemas/SidebarCategory" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" delete: tags: - channels summary: Delete sidebar category description: > Deletes a single sidebar category for the user on the given team. Only custom categories can be deleted. __Minimum server version__: 5.26 ##### Permissions Must be authenticated and have the `list_team_channels` permission. operationId: RemoveSidebarCategoryForTeamForUser parameters: - name: team_id in: path description: Team GUID required: true schema: type: string - name: user_id in: path description: User GUID required: true schema: type: string - name: category_id in: path description: Category GUID required: true schema: type: string responses: "200": description: Category delete successful content: application/json: schema: $ref: "#/components/schemas/SidebarCategory" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "/api/v4/channels/{channel_id}/common_teams": get: tags: - channels - group message summary: Get common teams for members of a Group Message. description: | Gets all the common teams for all active members of a Group Message channel. Returns empty list of no common teams are found. __Minimum server version__: 9.1 ##### Permissions Must be authenticated and have the `read_channel` permission for the channel. operationId: GetGroupMessageMembersCommonTeams parameters: - name: channel_id in: path description: Channel GUID required: true schema: type: string responses: "200": description: Common teams retrieval successful content: application/json: schema: type: array items: $ref: "#/components/schemas/Team" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" /api/v4/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. required: false 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. required: false 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: fromUpdateAt in: query description: The update_at timestamp to return the next page of posts from. You cannot set this flag with direction=down. 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 - name: updatesOnly in: query description: This flag is used to make the API work with the updateAt value. If you set this flag, you must set a value for fromUpdateAt. 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. required: false 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: 200 minimum: 0 - 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: 200 minimum: 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. THIS IS A BETA FEATURE. The API is subject to change without notice. ##### Permissions Must 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. __Minimum server version__: 9.3 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/posts/{post_id}/restore/{restore_version_id}": post: tags: - posts summary: Restores a past version of a post description: > Restores the post with `post_id` to its past version having the ID `restore_version_id`. ##### Permissions Must have `read_channel` permission for the channel the post is in. Must have `edit_post` permission for the channel the post is being moved to. Must be the author of the post being restored. __Minimum server version__: 10.5 operationId: RestorePostVersion parameters: - name: post_id in: path description: The identifier of the post to restore required: true schema: type: string - name: restore_version_id in: path description: The identifier of the past version of post to restore to required: true schema: type: string responses: "200": description: Post restored successful content: application/json: schema: $ref: "#/components/schemas/Post" "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/posts/{post_id}/reveal": get: tags: - posts summary: Reveal a burn-on-read post description: > Reveal a burn-on-read post. This endpoint allows a user to reveal a post that was created with burn-on-read functionality. Once revealed, the post content becomes visible to the user. If the post is already revealed and not expired, this is a no-op. If the post has expired, an error will be returned. ##### Permissions Must have `read_channel` permission for the channel the post is in.
Must be a member of the channel the post is in.
Cannot reveal your own post. ##### Feature Flag Requires `BurnOnRead` feature flag and Enterprise Advanced license. __Minimum server version__: 11.2 operationId: RevealPost parameters: - name: post_id in: path description: The identifier of the post to reveal required: true schema: type: string responses: "200": description: Post revealed successfully 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" "501": $ref: "#/components/responses/NotImplemented" "/api/v4/posts/{post_id}/burn": delete: tags: - posts summary: Burn a burn-on-read post description: > Burn a burn-on-read post. This endpoint allows a user to burn a post that was created with burn-on-read functionality. If the user is the author of the post, the post will be permanently deleted. If the user is not the author, the post will be expired for that user by updating their read receipt expiration time. If the user has not revealed the post yet, an error will be returned. If the post is already expired for the user, this is a no-op. ##### Permissions Must have `read_channel` permission for the channel the post is in.
Must be a member of the channel the post is in. ##### Feature Flag Requires `BurnOnRead` feature flag and Enterprise Advanced license. __Minimum server version__: 11.2 operationId: BurnPost parameters: - name: post_id in: path description: The identifier of the post to burn required: true schema: type: string responses: "200": description: Post burned successfully 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/StatusOK" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "501": $ref: "#/components/responses/NotImplemented" "/api/v4/posts/rewrite": post: tags: - posts summary: Rewrite a message using AI description: > Rewrite a message using AI based on the specified action. The message will be processed by an AI agent and returned in a rewritten form. ##### Permissions Must be authenticated. __Minimum server version__: 11.2 operationId: RewriteMessage requestBody: content: application/json: schema: type: object required: - agent_id - message - action properties: agent_id: type: string description: The ID of the AI agent to use for rewriting message: type: string description: The message text to rewrite action: type: string description: The rewrite action to perform enum: - custom - shorten - elaborate - improve_writing - fix_spelling - simplify - summarize custom_prompt: type: string description: Custom prompt for rewriting. Required when action is "custom", optional otherwise. description: Rewrite request object required: true responses: "200": description: Message rewritten successfully content: application/json: schema: type: object properties: rewritten_text: type: string description: The rewritten message text "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "500": description: Internal server error content: application/json: schema: $ref: "#/components/schemas/AppError" "/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 required: false schema: type: string - name: filename in: query description: The name of the file to be uploaded required: false 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 include `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/files/search": post: tags: - files - search summary: Search files across the teams of the current user description: > Search for files in the teams of the current user based on file name, extention and file content (if file content extraction is enabled and supported for the files). __Minimum server version__: 10.2 ##### Permissions Must be authenticated and have the `view_team` permission. operationId: SearchFiles requestBody: content: multipart/form-data: schema: type: object required: - terms - is_or_search properties: terms: type: string description: The search terms as entered 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 include `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. To resume an existing (incomplete) upload, data should be sent starting from the offset specified in the upload session object. The request body can be in one of two formats: - Binary file content streamed in request's body - multipart/form-data ##### Permissions Must be logged in as the user who created the upload session. 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: 5 - name: job_type in: query description: The type of jobs to fetch. schema: type: string - name: status in: query description: The status of jobs to fetch. schema: type: string 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/jobs/{job_id}/status": patch: tags: - jobs summary: Update the status of a job description: > Update the status of a job. Valid status updates: - 'in_progress' -> 'pending' - 'in_progress' | 'pending' -> 'cancel_requested' - 'cancel_requested' -> 'canceled' Add force to the body of the PATCH request to bypass the given rules, the only statuses you can go to are: pending, cancel_requested and canceled. This can have unexpected consequences and should be used with caution. operationId: UpdateJobStatus parameters: - name: job_id in: path description: Job GUID required: true schema: type: string requestBody: required: true content: application/json: schema: type: object required: - status properties: status: type: string description: The status you want to set force: type: boolean description: Set this to true to bypass status restrictions responses: "200": description: Status 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" /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. Authentication is not required for this endpoint. ##### Response Details The response varies based on query parameters and authentication: - **Basic response** (no parameters): Returns basic server information including `status`, mobile app versions, and active search backend. - **Enhanced response** (`get_server_status=true`): Additionally returns `database_status` and `filestore_status` to verify backend connectivity. Authentication is not required. - **Admin response** (`get_server_status=true` with `manage_system` permission): Additionally returns `root_status` indicating whether the server is running as root. Requires authentication with `manage_system` permission. operationId: GetPing parameters: - name: get_server_status in: query description: > Check the status of the database and file storage as well. When true, adds `database_status` and `filestore_status` to the response. If authenticated with `manage_system` permission, also adds `root_status`. required: false schema: type: boolean - name: device_id in: query description: Check whether this device id can receive push notifications required: false schema: type: string - name: use_rest_semantics in: query description: Returns 200 status code even if the server status is unhealthy. required: false 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 required: false 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/notifications/test: post: tags: - system summary: Send a test notification description: > Send a test notification to make sure you have your notification settings configured correctly. ##### Permissions Must be logged in. operationId: TestNotification responses: "200": description: Notification successfully 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 parameters: - name: remove_masked in: query description: | Remove masked values from the exported configuration. __Minimum server version__: 10.4.0 required: false schema: type: boolean default: false - name: remove_defaults in: query description: | Remove default values from the exported configuration. __Minimum server version__: 10.4.0 required: false schema: type: string default: false 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 responses: "200": description: Configuration retrieval successful /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/load_metric: get: tags: - system summary: Get license load metric description: > Get the current license load metric, calculated based on monthly active users against the licensed user count. Returns a value of 0 when there is no license loaded or the license doesn't have a user count. __Minimum server version__: 10.8 ##### Permissions Must be logged in. operationId: GetLicenseLoadMetric responses: "200": description: License load metric retrieval successful content: application/json: schema: type: object properties: load: type: integer description: Current license load metric as an integer "401": $ref: "#/components/responses/Unauthorized" "500": $ref: "#/components/responses/InternalServerError" /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 required: false 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 required: false 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 required: false 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/upgrade_to_enterprise/allowed: get: tags: - system summary: Check if the user is allowed to upgrade to Enterprise Edition description: > Check if the user is allowed to upgrade to Enterprise Edition operationId: IsAllowedToUpgradeToEnterprise responses: "200": description: User is allowed to upgrade to Enterprise Edition "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 parameters: - name: basic_server_logs in: query description: | Specifies whether the server should include or exclude log files. Default value is true. __Minimum server version__: 9.8.0 required: false schema: type: boolean - name: plugin_packets in: query description: | Specifies plugin identifiers whose content should be included in the Support Packet. __Minimum server version__: 9.8.0 required: false 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/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. channel_locked: type: boolean description: Whether the webhook is locked to the channel. 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 - name: include_total_count description: >- Appends a total count of returned hooks inside the response object - ex: `{ "incoming_webhooks": [], "total_count": 0 }`. in: query schema: type: boolean default: false 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. channel_locked: type: boolean description: Whether the webhook is locked to the channel. 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/test_connection: post: tags: - LDAP summary: Test LDAP connection with specific settings description: > Test the LDAP connection using the provided settings without modifying the current server configuration. ##### Permissions Must have `sysconsole_read_authentication_ldap` or `manage_system` permission. operationId: TestLdapConnection requestBody: description: LDAP settings to test required: true content: application/json: schema: $ref: "#/components/schemas/LdapSettings" responses: "200": description: LDAP connection test 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/test_diagnostics: post: tags: - LDAP summary: Test LDAP diagnostics with specific settings description: > Test LDAP diagnostics using the provided settings to validate configuration and see sample results without modifying the current server configuration. Use the `test` query parameter to specify which diagnostic to run. ##### Permissions Must have `sysconsole_read_authentication_ldap` or `manage_system` permission. operationId: TestLdapDiagnostics parameters: - in: query name: test required: true description: Type of LDAP diagnostic test to run schema: type: string enum: - filters - attributes - group_attributes example: filters requestBody: description: LDAP settings to test diagnostics with required: true content: application/json: schema: $ref: "#/components/schemas/LdapSettings" responses: "200": description: LDAP diagnostic test results content: application/json: schema: type: array items: $ref: "#/components/schemas/LdapDiagnosticResult" "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/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 required: false 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. 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. 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 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 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: - name - display_name - source - allow_reference - user_ids 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: type: array items: $ref: "#/components/schemas/GroupMember" 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: type: array items: $ref: "#/components/schemas/GroupMember" "/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 - name: include_member_count in: query description: Boolean which adds a `member_count` field to each group object. schema: type: boolean default: false - name: include_timezones in: query description: Boolean which adds timezone information for group members. schema: type: boolean default: false - name: include_total_count in: query description: Boolean which adds total count of groups in the response. schema: type: boolean default: false - name: include_archived in: query description: Boolean which includes archived groups in the response. schema: type: boolean default: false - name: filter_archived in: query description: Boolean which filters out archived groups from the response. schema: type: boolean default: false - name: filter_parent_team_permitted in: query description: Boolean which filters groups based on parent team permissions. schema: type: boolean default: false - name: filter_has_member in: query description: User ID to filter groups that have this member. schema: type: string - name: include_member_ids in: query description: Boolean which adds member IDs to the group objects. schema: type: boolean default: false - name: only_syncable_sources in: query description: Boolean which includes groups from syncable sources. 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/groups/names": post: tags: - groups summary: Get groups by name description: | Get a list of groups based on a provided list of names. ##### Permissions Requires an active session but no other permissions. __Minimum server version__: 11.0 operationId: GetGroupsByNames requestBody: content: application/json: schema: type: array items: type: string description: List of group names required: true responses: "200": description: Group list retrieval successfully content: application/json: schema: type: array items: $ref: "#/components/schemas/Group" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "501": $ref: "#/components/responses/NotImplemented" /api/v4/cluster/status: get: tags: - cluster summary: Get cluster status description: > Get a list of all healthy nodes, including local information and status of each one. If a node is not present, it means it is not healthy. ##### 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 is_public: type: boolean description: Set this to `true` to create a public client (no client secret). Public clients must use PKCE for authorization. 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 ##### Permissions If app creator, must have `mange_oauth` permission otherwise `manage_system_wide_oauth` permission is required. 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" /.well-known/oauth-authorization-server: get: tags: - OAuth summary: Get OAuth 2.0 Authorization Server Metadata description: > Get the OAuth 2.0 Authorization Server Metadata as defined in RFC 8414. This endpoint provides metadata about the OAuth 2.0 authorization server's configuration, including supported endpoints, grant types, response types, and authentication methods. ##### Permissions No authentication required. This endpoint is publicly accessible to allow OAuth clients to discover the authorization server's configuration. ##### Notes - This endpoint implements RFC 8414 (OAuth 2.0 Authorization Server Metadata) - The metadata is dynamically generated based on the server's configuration - OAuth Service Provider must be enabled in system settings for this endpoint to be available operationId: GetAuthorizationServerMetadata responses: "200": description: Metadata retrieval successful content: application/json: schema: $ref: "#/components/schemas/AuthorizationServerMetadata" "501": description: OAuth Service Provider is not enabled content: application/json: schema: $ref: "#/components/schemas/AppError" /api/v4/oauth/apps/register: post: tags: - OAuth summary: Register OAuth client using Dynamic Client Registration description: > Register an OAuth 2.0 client application using Dynamic Client Registration (DCR) as defined in RFC 7591. This endpoint allows clients to register without requiring administrative approval. ##### Permissions No authentication required. This endpoint implements the OAuth 2.0 Dynamic Client Registration Protocol and can be called by unauthenticated clients. ##### Notes - This endpoint follows RFC 7591 (OAuth 2.0 Dynamic Client Registration Protocol) - The `client_uri` field, when provided, will be mapped to the OAuth app's homepage - All registered clients are marked as dynamically registered - Dynamic client registration must be enabled in system settings operationId: RegisterOAuthClient requestBody: content: application/json: schema: $ref: "#/components/schemas/ClientRegistrationRequest" description: OAuth client registration request required: true responses: "201": description: Client registration successful content: application/json: schema: $ref: "#/components/schemas/ClientRegistrationResponse" "400": $ref: "#/components/responses/BadRequest" "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. 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. 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. 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 required: false 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) required: false schema: type: integer - name: per_page in: query description: Number of item per page. (not yet implemented) required: false schema: type: integer - name: filter in: query description: Set to filter plugins by ID, name, or description. required: false schema: type: string - name: server_version in: query description: Set to filter minimum plugin server version. (not yet implemented) required: false schema: type: string - name: local_only in: query description: Set true to only retrieve local plugins. required: false 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 Must have `sysconsole_write_user_management_permissions` or `manage_system` permission. When updating the role of a system admin, the `manage_system` permission is mandatory. __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: - display_name - scope properties: name: type: string description: The name of the scheme display_name: type: string description: The display 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/remotecluster": get: tags: - remote clusters summary: Get a list of remote clusters. description: | Get a list of remote clusters. ##### Permissions `manage_secure_connections` operationId: GetRemoteClusters parameters: - name: page in: query description: The page to select schema: type: integer - name: per_page in: query description: The number of remote clusters per page schema: type: integer - name: exclude_offline in: query description: Exclude offline remote clusters schema: type: boolean - name: in_channel in: query description: Select remote clusters in channel schema: type: string - name: not_in_channel in: query description: Select remote clusters not in this channel schema: type: string - name: only_confirmed in: query description: Select only remote clusters already confirmed schema: type: boolean - name: only_plugins in: query description: Select only remote clusters that belong to a plugin schema: type: boolean - name: exclude_plugins in: query description: Select only remote clusters that don't belong to a plugin schema: type: boolean - name: include_deleted in: query description: Include those remote clusters that have been deleted schema: type: boolean responses: "200": description: Remote clusters fetch successful. Result might be empty. content: application/json: schema: type: array items: $ref: "#/components/schemas/RemoteCluster" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" post: tags: - remote clusters summary: Create a new remote cluster. description: | Create a new remote cluster and generate an invite code. ##### Permissions `manage_secure_connections` operationId: CreateRemoteCluster requestBody: content: application/json: schema: type: object required: - name - default_team_id properties: name: type: string display_name: type: string default_team_id: type: string password: type: string description: | The password to use in the invite code. If empty, the server will generate one and it will be part of the response responses: "201": description: Remote cluster creation successful content: application/json: schema: type: object properties: remote_cluster: $ref: "#/components/schemas/RemoteCluster" invite: type: string description: The encrypted invite for the newly created remote cluster password: type: string description: | The password generated by the server if none was sent on the create request "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "/api/v4/remotecluster/{remote_id}": get: tags: - remote clusters summary: Get a remote cluster. description: | Get the Remote Cluster details from the provided id string. ##### Permissions `manage_secure_connections` operationId: GetRemoteCluster parameters: - name: remote_id in: path description: Remote Cluster GUID required: true schema: type: string responses: "200": description: Remote Cluster retrieval successful content: application/json: schema: $ref: "#/components/schemas/RemoteCluster" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" patch: tags: - remote clusters summary: Patch a remote cluster. description: | Partially update a Remote Cluster by providing only the fields you want to update. Ommited fields will not be updated. ##### Permissions `manage_secure_connections` operationId: PatchRemoteCluster parameters: - name: remote_id in: path description: Remote Cluster GUID required: true schema: type: string requestBody: content: application/json: schema: type: object properties: display_name: type: string default_team_id: type: string description: The team where channels from invites are created responses: "200": description: Remote Cluster patch successful content: application/json: schema: $ref: "#/components/schemas/RemoteCluster" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" delete: tags: - remote clusters summary: Delete a remote cluster. description: | Deletes a Remote Cluster. ##### Permissions `manage_secure_connections` operationId: DeleteRemoteCluster parameters: - name: remote_id in: path description: Remote Cluster GUID required: true schema: type: string responses: "204": description: Remote Cluster deletion successful "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "/api/v4/remotecluster/{remote_id}/generate_invite": post: tags: - remote clusters summary: Generate invite code. description: | Generates an invite code for a given remote cluster. ##### Permissions `manage_secure_connections` operationId: GenerateRemoteClusterInvite requestBody: content: application/json: schema: type: object required: - password properties: password: type: string description: The password to encrypt the invite code with. responses: "201": description: Invite code generated content: application/json: schema: type: string "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "/api/v4/remotecluster/accept_invite": post: tags: - remote clusters summary: Accept a remote cluster invite code. description: | Accepts a remote cluster invite code. ##### Permissions `manage_secure_connections` operationId: AcceptRemoteClusterInvite requestBody: content: application/json: schema: type: object required: - invite - name - default_team_id - password properties: invite: type: string name: type: string display_name: type: string default_team_id: type: string password: type: string description: The password to decrypt the invite code. responses: "201": description: Invite successfully accepted content: application/json: schema: type: object $ref: "#/components/schemas/RemoteCluster" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "/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/remotecluster/{remote_id}/sharedchannelremotes": get: tags: - shared channels summary: Get shared channel remotes by remote cluster. description: | Get a list of the channels shared with a given remote cluster and their status. ##### Permissions `manage_secure_connections` operationId: GetSharedChannelRemotesByRemoteCluster parameters: - name: remote_id in: path description: The remote cluster GUID required: true schema: type: string - name: include_unconfirmed in: query description: Include those Shared channel remotes that are unconfirmed schema: type: boolean - name: exclude_confirmed in: query description: Show only those Shared channel remotes that are not confirmed yet schema: type: boolean - name: exclude_home in: query description: Show only those Shared channel remotes that were shared with this server schema: type: boolean - name: exclude_remote in: query description: Show only those Shared channel remotes that were shared from this server schema: type: boolean - name: include_deleted in: query description: Include those Shared channel remotes that have been deleted schema: type: boolean - name: page in: query description: The page to select schema: type: integer - name: per_page in: query description: The number of shared channels per page schema: type: integer responses: "200": description: Shared channel remotes fetch successful. Result might be empty. content: application/json: schema: type: array items: $ref: "#/components/schemas/SharedChannelRemote" "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/remotecluster/{remote_id}/channels/{channel_id}/invite": post: tags: - shared channels summary: Invites a remote cluster to a channel. description: | Invites a remote cluster to a channel, sharing the channel if needed. If the remote cluster was already invited to the channel, calling this endpoint will have no effect. ##### Permissions `manage_shared_channels` operationId: InviteRemoteClusterToChannel parameters: - name: remote_id in: path description: The remote cluster GUID required: true schema: type: string - name: channel_id in: path description: The channel GUID to invite the remote cluster to required: true schema: type: string responses: "200": description: Remote cluster invited successfully content: application/json: schema: $ref: "#/components/schemas/StatusOK" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "/api/v4/remotecluster/{remote_id}/channels/{channel_id}/uninvite": post: tags: - shared channels summary: Uninvites a remote cluster to a channel. description: | Stops sharing a channel with a remote cluster. If the channel was not shared with the remote, calling this endpoint will have no effect. ##### Permissions `manage_shared_channels` operationId: UninviteRemoteClusterToChannel parameters: - name: remote_id in: path description: The remote cluster GUID required: true schema: type: string - name: channel_id in: path description: The channel GUID to uninvite the remote cluster to required: true schema: type: string responses: "200": description: Remote cluster uninvited successfully content: application/json: schema: $ref: "#/components/schemas/StatusOK" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "/api/v4/sharedchannels/{channel_id}/remotes": get: tags: - shared channels summary: Get remote clusters for a shared channel description: | Gets the remote clusters information for a shared channel. __Minimum server version__: 10.11 ##### Permissions Must be authenticated and have the `read_channel` permission for the channel. operationId: GetSharedChannelRemotes parameters: - name: channel_id in: path description: Channel GUID required: true schema: type: string responses: "200": description: Remote clusters retrieval successful content: application/json: schema: type: array items: $ref: "#/components/schemas/RemoteClusterInfo" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "/api/v4/sharedchannels/users/{user_id}/can_dm/{other_user_id}": get: tags: - shared channels summary: Check if user can DM another user in shared channels context description: | Checks if a user can send direct messages to another user, considering shared channel restrictions. This is specifically for shared channels where DMs require direct connections between clusters. __Minimum server version__: 10.11 ##### Permissions Must be authenticated and have permission to view the user. operationId: CanUserDirectMessage parameters: - name: user_id in: path description: User GUID required: true schema: type: string - name: other_user_id in: path description: Other user GUID required: true schema: type: string responses: "200": description: DM permission check successful content: application/json: schema: type: object properties: can_dm: type: boolean description: Whether the user can send DMs to the other user "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/actions/dialogs/lookup: post: tags: - integration_actions summary: Lookup dialog elements description: > Endpoint used by the Mattermost clients to lookup dynamic dialog elements. See https://docs.mattermost.com/developer/interactive-dialogs.html for more information on interactive dialogs. __Minimum server version: 11.0__ operationId: LookupInteractiveDialog requestBody: content: application/json: schema: type: object required: - url - submission - channel_id - team_id properties: url: type: string description: The URL to send the lookup request to channel_id: type: string description: Channel ID the user is performing the lookup from team_id: type: string description: Team ID the user is performing the lookup 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 description: Dialog lookup request data required: true responses: "200": description: Dialog lookup successful content: application/json: schema: type: object properties: options: type: array description: List of options returned from the lookup items: type: object properties: text: type: string description: Display text for the option value: type: string description: Value for the option "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. 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. ##### Permissions Must have `manage_bots` permission. __Minimum server version__: 5.10 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. ##### Permissions Must have `manage_bots` permission. __Minimum server version__: 5.10 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. ##### Permissions Must have `manage_bots` permission. __Minimum server version__: 5.10 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. ##### Permissions Must have `manage_bots` permission. __Minimum server version__: 5.10 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/cloud/preview/modal_data: get: tags: - cloud summary: Get cloud preview modal data description: > Retrieves modal content data from the configured S3 bucket for displaying cloud product preview modals. ##### Permissions Must be authenticated. Must be in a Cloud Preview environment. __Minimum server version__: 10.0 __Note:__ This is intended for internal use and is subject to change. operationId: GetPreviewModalData responses: "200": description: Preview modal data returned successfully content: application/json: schema: type: array items: $ref: "#/components/schemas/PreviewModalContentData" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalServerError" /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: post: 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__: 9.10 operationId: GetAncillaryPermissionsPost requestBody: content: application/json: schema: type: array items: type: string description: List of subsection permissions required: true 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/imports/{import_name}": delete: tags: - imports summary: Delete an import file description: | Deletes an import file. __Minimum server version__: 5.31 ##### Permissions Must have `manage_system` permissions. operationId: DeleteImport parameters: - name: import_name in: path description: The name of the import 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/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 required: false 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 body: 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 body: 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 body: 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: - reports 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. ##### 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 to accept paging values from. Will return values ahead of the cursor if "prev", and below the cursor if "next". Default is "next". schema: type: string default: 'next' - 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: 1 maximum: 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: - reports 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. ##### 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. ##### 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/reports/posts: post: tags: - reports summary: Get posts for reporting and compliance purposes using cursor-based pagination description: > Get posts from a specific channel for reporting, compliance, and auditing purposes. This endpoint uses cursor-based pagination to efficiently retrieve large datasets. The cursor is an opaque, base64-encoded token that contains all pagination state. Clients should treat the cursor as an opaque string and pass it back unchanged. When a cursor is provided, query parameters from the initial request are embedded in the cursor and take precedence over request body parameters. ##### Permissions Requires `manage_system` permission (system admin only). ##### License Requires an Enterprise license (or higher). ##### Features - Cursor-based pagination for efficient large dataset retrieval - Support for both create_at and update_at time fields - Ascending or descending sort order - Time range filtering with optional end_time - Include/exclude deleted posts - Exclude system posts (any type starting with "system_") - Optional metadata enrichment (file info, reactions, emojis, priority, acknowledgements) operationId: GetPostsForReporting requestBody: required: true content: application/json: schema: type: object required: - channel_id properties: channel_id: type: string description: The ID of the channel to retrieve posts from cursor: type: string description: > Opaque cursor string for pagination. Omit or use empty string for the first request. For subsequent requests, use the exact cursor value from the previous response's next_cursor. The cursor is base64-encoded and contains all pagination state including time, post ID, and query parameters. Do not attempt to parse or modify the cursor value. default: "" start_time: type: integer format: int64 description: > Optional start time for query range in Unix milliseconds. Only used for the first request (ignored when cursor is provided). - For "asc" (ascending): starts retrieving from this time going forward - For "desc" (descending): starts retrieving from this time going backward If omitted, defaults to 0 for ascending or MaxInt64 for descending. time_field: type: string enum: [create_at, update_at] default: create_at description: > Which timestamp field to use for sorting and filtering. Use "create_at" to retrieve posts by creation time, or "update_at" to retrieve posts by last modification time. sort_direction: type: string enum: [asc, desc] default: asc description: > Sort direction for pagination. Use "asc" to retrieve posts from oldest to newest, or "desc" to retrieve from newest to oldest. per_page: type: integer minimum: 1 maximum: 1000 default: 100 description: Number of posts to return per page. Maximum 1000. include_deleted: type: boolean default: false description: > If true, include posts that have been deleted (DeleteAt > 0). By default, only non-deleted posts are returned. exclude_system_posts: type: boolean default: false description: > If true, exclude all system posts. include_metadata: type: boolean default: false description: > If true, enrich posts with additional metadata including file information, reactions, custom emojis, priority, and acknowledgements. Note that this may increase response time for large result sets. examples: first_page_ascending: summary: First page, ascending order value: channel_id: "4xp9fdt77pncbef59f4k1qe83o" cursor: "" per_page: 100 subsequent_page: summary: Subsequent page using cursor value: channel_id: "4xp9fdt77pncbef59f4k1qe83o" cursor: "MTphYmMxMjM6Y3JlYXRlX2F0OmZhbHNlOmZhbHNlOmFzYzoxNjM1NzI0ODAwMDAwOnBvc3QxMjM" per_page: 100 time_range_query: summary: Query with time range starting from specific time value: channel_id: "4xp9fdt77pncbef59f4k1qe83o" cursor: "" start_time: 1635638400000 per_page: 100 descending_order: summary: Descending order from recent value: channel_id: "4xp9fdt77pncbef59f4k1qe83o" cursor: "" sort_direction: "desc" per_page: 100 responses: "200": description: Posts retrieved successfully content: application/json: schema: type: object properties: posts: type: object additionalProperties: $ref: "#/components/schemas/Post" description: Map of post IDs to post objects next_cursor: type: object nullable: true description: > Opaque cursor for retrieving the next page. If null, there are no more pages. Pass the cursor string from this object in the next request. properties: cursor: type: string description: Base64-encoded opaque cursor string containing pagination state examples: with_more_pages: summary: Response with more pages available value: posts: "post_id_1": { "id": "post_id_1", "message": "First post", "create_at": 1635638400000 } "post_id_2": { "id": "post_id_2", "message": "Second post", "create_at": 1635638500000 } next_cursor: cursor: "MTphYmMxMjM6Y3JlYXRlX2F0OmZhbHNlOmZhbHNlOmFzYzoxNjM1NjM4NTAwMDAwOnBvc3RfaWRfMg" last_page: summary: Last page (no more results) value: posts: "post_id_99": { "id": "post_id_99", "message": "Last post", "create_at": 1635724800000 } next_cursor: null "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "500": $ref: "#/components/responses/InternalServerError" /api/v4/limits/server: get: tags: - users summary: Gets the server limits for the server description: > Gets the server limits for the server ##### Permissions Requires `sysconsole_read_user_management_users`. operationId: GetServerLimits responses: "200": description: App limits for server content: application/json: schema: type: array items: $ref: "#/components/schemas/ServerLimits" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "500": $ref: "#/components/responses/InternalServerError" /api/v4/logs/download: get: tags: - logs summary: Download system logs description: > Downloads the system logs as a text file. operationId: DownloadSystemLogs responses: "200": description: System logs downloaded successfully. content: text/plain: schema: type: string format: binary "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": description: The connection configuration is invalid. $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": description: The connection configuration may be valid, but the server is unable to validate it upstream. $ref: "#/components/responses/BadGateway" /api/v4/client_perf: post: tags: - metrics summary: Report client performance metrics description: > Uploads client performance measurements to the server as part of the Client Performance Monitoring feature. __Minimum server version__: 9.9.0 operationId: SubmitPerformanceReport requestBody: content: application/json: schema: type: object required: - version - start - end properties: version: type: string description: An identifier for the schema of the data being submitted which currently must be "0.1.0" client_id: type: string description: Not currently used labels: type: array items: type: string description: Labels to be applied to all metrics when recorded by the metrics backend start: type: integer format: int64 description: The time in milliseconds of the first metric in this report end: type: integer format: int64 description: The time in milliseconds of the last metric in this report counters: type: array items: type: object required: - metric - value properties: metric: type: string description: The name of the counter value: type: number format: double description: The value to increment the counter by timestamp: type: integer format: int64 description: The time that the counter was incremented labels: type: array items: type: string description: Labels to be applied to this metric when recorded by the metrics backend description: An array of counter metrics to be reported histograms: type: array items: type: object required: - metric - value properties: metric: type: string description: The name of the measurement value: type: number format: double description: The value of the measurement timestamp: type: integer format: int64 description: The time that the measurement was taken labels: type: array items: type: string description: Labels to be applied to this metric when recorded by the metrics backend description: An array of histogram measurements to be reported responses: "200": description: Measurements reported successfully 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" /api/v4/posts/schedule: post: tags: - scheduled_post summary: Creates a scheduled post description: > Creates a scheduled post ##### Permissions Must have `create_post` permission for the channel the post is being created in. __Minimum server version__: 10.3 operationId: CreateScheduledPost requestBody: content: application/json: schema: type: object required: - channel_id - message - scheduled_at properties: scheduled_at: type: integer description: UNIX timestamp in milliseconds of the time when the scheduled post should be sent 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. props: description: A general JSON property bag to attach to the post type: object responses: "200": description: Created scheduled post content: application/json: schema: type: object items: $ref: "#/components/schemas/ScheduledPost" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "500": $ref: "#/components/responses/InternalServerError" /api/v4/posts/scheduled/team/{team_id}: get: tags: - scheduled_post summary: Gets all scheduled posts for a user for the specified team.. description: > Get user-team scheduled posts ##### Permissions Must have `view_team` permission for the team the scheduled posts are being fetched for. __Minimum server version__: 10.3 operationId: GetUserScheduledPosts parameters: - name: includeDirectChannels in: query description: Whether to include scheduled posts from DMs an GMs or not. Default is false required: false schema: type: boolean default: false responses: "200": description: Created scheduled post content: application/json: schema: type: object additionalProperties: type: array items: $ref: "#/components/schemas/ScheduledPost" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "500": $ref: "#/components/responses/InternalServerError" /api/v4/posts/schedule/{scheduled_post_id}: put: tags: - scheduled_post summary: Update a scheduled post description: > Updates a scheduled post ##### Permissions Must have `create_post` permission for the channel where the scheduled post belongs to. __Minimum server version__: 10.3 operationId: UpdateScheduledPost parameters: - name: scheduled_post_id in: path description: ID of the scheduled post to update required: true schema: type: string requestBody: content: application/json: schema: type: object required: - id - channel_id - user_id - message - scheduled_at properties: id: description: ID of the scheduled post to update type: string channel_id: type: string description: The channel ID to post in user_id: type: string description: The current user ID scheduled_at: type: integer description: UNIX timestamp in milliseconds of the time when the scheduled post should be sent message: type: string description: The message contents, can be formatted with Markdown responses: "200": description: Updated scheduled post content: application/json: schema: type: object items: $ref: "#/components/schemas/ScheduledPost" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "500": $ref: "#/components/responses/InternalServerError" delete: tags: - scheduled_post summary: Delete a scheduled post description: > Delete a scheduled post __Minimum server version__: 10.3 operationId: DeleteScheduledPost parameters: - name: scheduled_post_id in: path description: ID of the scheduled post to delete required: true schema: type: string responses: "200": description: Deleted scheduled post content: application/json: schema: type: object items: $ref: "#/components/schemas/ScheduledPost" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "500": $ref: "#/components/responses/InternalServerError" "/api/v4/custom_profile_attributes/fields": get: tags: - custom profile attributes summary: List all the Custom Profile Attributes fields description: | List all the Custom Profile Attributes fields. _This endpoint is experimental._ __Minimum server version__: 10.5 ##### Permissions Must be authenticated. operationId: ListAllCPAFields responses: "200": description: Custom Profile Attributes fetch successful. Result may be empty. content: application/json: schema: type: array items: $ref: "#/components/schemas/PropertyField" "401": $ref: "#/components/responses/Unauthorized" post: tags: - custom profile attributes summary: Create a Custom Profile Attribute field description: | Create a new Custom Profile Attribute field on the system. _This endpoint is experimental._ __Minimum server version__: 10.5 ##### Permissions Must have `manage_system` permission. operationId: CreateCPAField requestBody: content: application/json: schema: type: object required: - name - type properties: name: type: string type: type: string attrs: type: object properties: visibility: type: string description: "Visibility of the attribute" enum: ["hidden", "when_set", "always"] default: "when_set" sort_order: type: number description: "Sort order for displaying this attribute" options: type: array description: "Options for select/multiselect fields" items: type: object properties: name: type: string color: type: string value_type: type: string description: "Type of text value" enum: ["email", "url", "phone"] ldap: type: string description: "LDAP attribute for syncing" saml: type: string description: "SAML attribute for syncing" responses: "201": description: Custom Profile Attribute field creation successful content: application/json: schema: $ref: "#/components/schemas/PropertyField" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "/api/v4/custom_profile_attributes/fields/{field_id}": patch: tags: - custom profile attributes summary: Patch a Custom Profile Attribute field description: | Partially update a Custom Profile Attribute field 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. _This endpoint is experimental._ __Minimum server version__: 10.5 ##### Permissions Must have `manage_system` permission. operationId: PatchCPAField parameters: - name: field_id in: path description: Custom Profile Attribute field GUID required: true schema: type: string requestBody: description: Custom Profile Attribute field that is to be updated required: true content: application/json: schema: type: object properties: name: type: string type: type: string attrs: type: object properties: visibility: type: string description: "Visibility of the attribute" enum: ["hidden", "when_set", "always"] default: "when_set" sort_order: type: number description: "Sort order for displaying this attribute" options: type: array description: "Options for select/multiselect fields" items: type: object properties: id: type: string name: type: string color: type: string value_type: type: string description: "Type of text value" enum: ["email", "url", "phone"] ldap: type: string description: "LDAP attribute for syncing" saml: type: string description: "SAML attribute for syncing" responses: "200": description: Custom Profile Attribute field patch successful content: application/json: schema: $ref: "#/components/schemas/PropertyField" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" delete: tags: - custom profile attributes summary: Delete a Custom Profile Attribute field description: | Marks a Custom Profile Attribute field and all its values as deleted. _This endpoint is experimental._ __Minimum server version__: 10.5 ##### Permissions Must have `manage_system` permission. operationId: DeleteCPAField parameters: - name: field_id in: path description: Custom Profile Attribute field GUID required: true schema: type: string responses: "200": description: Custom Profile Attribute field 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/custom_profile_attributes/values": patch: tags: - custom profile attributes summary: Patch Custom Profile Attribute values description: | Partially update a set of values on the requester's Custom Profile Attribute fields by providing only the information 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. _This endpoint is experimental._ __Minimum server version__: 10.5 ##### Permissions Must be authenticated. operationId: PatchCPAValues requestBody: description: Custom Profile Attribute values that are to be updated required: true content: application/json: schema: type: array items: type: object properties: id: type: string value: oneOf: - type: string - type: array items: type: string responses: "200": description: Custom Profile Attribute values patch successful content: application/json: schema: type: array items: type: object properties: id: type: string value: oneOf: - type: string - type: array items: type: string "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "/api/v4/custom_profile_attributes/group": get: tags: - custom profile attributes summary: Get Custom Profile Attribute property group data description: | Get the property group used for Custom Profile Attributes. __Minimum server version__: 10.8 ##### Permissions Must be authenticated. operationId: GetCPAGroup responses: "200": description: Group fetch successful content: application/json: schema: type: object properties: id: type: string description: The ID of the custom profile attributes group "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "/api/v4/users/{user_id}/custom_profile_attributes": get: tags: - custom profile attributes summary: List Custom Profile Attribute values description: | List all the Custom Profile Attributes values for specified user. _This endpoint is experimental._ __Minimum server version__: 10.5 ##### Permissions Must have `view members` permission. operationId: ListCPAValues parameters: - name: user_id in: path description: User GUID required: true schema: type: string responses: "200": description: Custom Profile Attribute values fetch successful. Result may be empty. content: application/json: schema: type: array items: type: object properties: field_id: type: string value: type: string "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" patch: tags: - custom profile attributes summary: Update custom profile attribute values for a user description: | Update Custom Profile Attribute field values for a specific user. _This endpoint is experimental._ __Minimum server version__: 11 ##### Permissions Must have permission to edit the user. Users can only edit their own CPA values unless they are system administrators. parameters: - name: user_id in: path description: User GUID required: true schema: type: string operationId: PatchCPAValuesForUser requestBody: description: Custom Profile Attribute values that are to be updated required: true content: application/json: schema: type: array items: type: object properties: id: type: string value: oneOf: - type: string - type: array items: type: string responses: '200': description: Custom profile attribute values updated successfully content: application/json: schema: type: array items: type: object properties: id: type: string value: oneOf: - type: string - type: array items: type: string '400': $ref: '#/components/responses/BadRequest' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /api/v4/audit_logs/certificate: post: tags: - audit_logs summary: Upload audit log certificate description: | Upload the certificate to be used for TLS verification with the audit log service. ##### Permissions Must have `sysconsole_write_experimental_features` permission. __Minimum server version__: 10.9 operationId: AddAuditLogCertificate requestBody: content: multipart/form-data: schema: type: object properties: certificate: description: The certificate file type: string format: binary required: - certificate responses: "200": description: 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" "413": $ref: "#/components/responses/TooLarge" "501": $ref: "#/components/responses/NotImplemented" delete: tags: - audit_logs summary: Remove audit log certificate description: | Delete the current certificate being used with the audit log service. ##### Permissions Must have `sysconsole_write_experimental_features` permission. __Minimum server version__: 9.5 operationId: RemoveAuditLogCertificate responses: "200": description: Certificate deletion 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/access_control_policies: put: tags: - access control summary: Create an access control policy description: | Creates a new access control policy. ##### Permissions Must have the `manage_system` permission. operationId: CreateAccessControlPolicy requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AccessControlPolicy" responses: "200": description: Access control policy created successfully. content: application/json: schema: $ref: "#/components/schemas/AccessControlPolicy" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "500": $ref: "#/components/responses/InternalServerError" /api/v4/access_control_policies/cel/check: post: tags: - access control summary: Check an access control policy expression description: | Checks the syntax and validity of an access control policy expression. ##### Permissions Must have the `manage_system` permission. operationId: CheckAccessControlPolicyExpression requestBody: required: true content: application/json: schema: type: object properties: expression: type: string description: The expression to check. responses: "200": description: Expression check result. content: application/json: schema: type: array items: $ref: "#/components/schemas/ExpressionError" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "500": $ref: "#/components/responses/InternalServerError" /api/v4/access_control_policies/cel/validate_requester: post: tags: - access control summary: Validate if the current user matches a CEL expression description: | Validates whether the current authenticated user matches the given CEL expression. This is used to determine if a channel admin can test expressions they match. ##### Permissions Must have `manage_system` permission OR be a channel admin for the specified channel (channelId required for channel admins). operationId: ValidateExpressionAgainstRequester requestBody: required: true content: application/json: schema: type: object properties: expression: type: string description: The CEL expression to validate against the current user. channelId: type: string description: The channel ID for channel-specific permission checks (required for channel admins). required: - expression responses: "200": description: Validation result returned successfully. content: application/json: schema: type: object properties: requester_matches: type: boolean description: Whether the current user matches the expression. required: - requester_matches "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "500": $ref: "#/components/responses/InternalServerError" /api/v4/access_control_policies/cel/test: post: tags: - access control summary: Test an access control policy expression description: | Tests an access control policy expression against users to see who would be affected. ##### Permissions Must have the `manage_system` permission. operationId: TestAccessControlPolicyExpression requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/QueryExpressionParams" responses: "200": description: Expression test result. content: application/json: schema: $ref: "#/components/schemas/AccessControlPolicyTestResponse" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "500": $ref: "#/components/responses/InternalServerError" /api/v4/access_control_policies/search: post: tags: - access control summary: Search access control policies description: | Searches for access control policies based on given criteria. ##### Permissions Must have the `manage_system` permission. operationId: SearchAccessControlPolicies requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AccessControlPolicySearch" responses: "200": description: Search results for access control policies. content: application/json: schema: $ref: "#/components/schemas/AccessControlPoliciesWithCount" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "500": $ref: "#/components/responses/InternalServerError" /api/v4/access_control_policies/cel/autocomplete/fields: get: tags: - access control summary: Get autocomplete fields for access control policies description: | Provides a list of fields that can be used for autocompletion when creating/editing access control policy expressions. ##### Permissions Must have the `manage_system` permission. operationId: GetAccessControlPolicyAutocompleteFields parameters: - name: after in: query description: The field ID to start after for pagination. required: false schema: type: string - name: limit in: query description: The maximum number of fields to return. required: true schema: type: integer default: 60 responses: "200": description: Autocomplete fields retrieved successfully. content: application/json: schema: $ref: "#/components/schemas/AccessControlFieldsAutocompleteResponse" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "500": $ref: "#/components/responses/InternalServerError" "/api/v4/access_control_policies/{policy_id}": get: tags: - access control summary: Get an access control policy description: | Gets a specific access control policy by its ID. ##### Permissions Must have the `manage_system` permission. operationId: GetAccessControlPolicy parameters: - name: policy_id in: path description: The ID of the access control policy. required: true schema: type: string responses: "200": description: Access control policy retrieved successfully. content: application/json: schema: $ref: "#/components/schemas/AccessControlPolicy" "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: - access control summary: Delete an access control policy description: | Deletes an access control policy by its ID. ##### Permissions Must have the `manage_system` permission. operationId: DeleteAccessControlPolicy parameters: - name: policy_id in: path description: The ID of the access control policy. required: true schema: type: string responses: "200": description: Access control policy 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" "500": $ref: "#/components/responses/InternalServerError" "/api/v4/access_control_policies/{policy_id}/activate": get: tags: - access control summary: Activate or deactivate an access control policy description: | Updates the active status of an access control policy. ##### Permissions Must have the `manage_system` permission. operationId: UpdateAccessControlPolicyActiveStatus parameters: - name: policy_id in: path description: The ID of the access control policy. required: true schema: type: string - name: active in: query description: Set to "true" to activate, "false" to deactivate. required: true schema: type: boolean responses: "200": description: Policy active status 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" "500": $ref: "#/components/responses/InternalServerError" "/api/v4/access_control_policies/{policy_id}/assign": post: tags: - access control summary: Assign an access control policy to channels description: | Assigns an access control policy to a list of channels. ##### Permissions Must have the `manage_system` permission. operationId: AssignAccessControlPolicyToChannels parameters: - name: policy_id in: path description: The ID of the access control policy. required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: channel_ids: type: array items: type: string description: The IDs of the channels to assign the policy to. responses: "200": description: Policy assigned to channels 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" "500": $ref: "#/components/responses/InternalServerError" "/api/v4/access_control_policies/{policy_id}/unassign": delete: tags: - access control summary: Unassign an access control policy from channels description: | Unassigns an access control policy from a list of channels. ##### Permissions Must have the `manage_system` permission. operationId: UnassignAccessControlPolicyFromChannels parameters: - name: policy_id in: path description: The ID of the access control policy. required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: channel_ids: type: array items: type: string description: The IDs of the channels to unassign the policy from. responses: "200": description: Policy unassigned from channels 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" "500": $ref: "#/components/responses/InternalServerError" "/api/v4/access_control_policies/{policy_id}/resources/channels": get: tags: - access control summary: Get channels for an access control policy description: | Retrieves a paginated list of channels to which a specific access control policy is applied. ##### Permissions Must have the `manage_system` permission. operationId: GetChannelsForAccessControlPolicy parameters: - name: policy_id in: path description: The ID of the access control policy. required: true schema: type: string - name: after in: query description: The channel ID to start after for pagination. required: false schema: type: string - name: limit in: query description: The maximum number of channels to return. required: true schema: type: integer default: 60 responses: "200": description: Channels retrieved successfully. content: application/json: schema: $ref: "#/components/schemas/ChannelsWithCount" "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" "/api/v4/access_control_policies/{policy_id}/resources/channels/search": post: tags: - access control summary: Search channels for an access control policy description: | Searches for channels associated with a specific access control policy based on search criteria. ##### Permissions Must have the `manage_system` permission. operationId: SearchChannelsForAccessControlPolicy parameters: - name: policy_id in: path description: The ID of the access control policy. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ChannelSearch" responses: "200": description: Channel search results retrieved successfully. content: application/json: schema: $ref: "#/components/schemas/ChannelsWithCount" "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" "/api/v4/channels/{channel_id}/access_control/attributes": get: tags: - access control - channels summary: Get access control attributes for a channel description: | Retrieves the effective access control policy attributes for a specific channel. This can be used to understand what attributes are currently being applied to the channel by the access control system. ##### Permissions Must have `read_channel` permission for the specified channel. operationId: GetChannelAccessControlAttributes parameters: - name: channel_id in: path description: The ID of the channel. required: true schema: type: string responses: "200": description: Access control attributes retrieved successfully. content: application/json: schema: type: object # Placeholder - define more specifically if the structure is known additionalProperties: true description: A map of attribute names to their values as applied to the channel. "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" /api/v4/access_control_policies/cel/visual_ast: post: tags: - access control summary: Get the visual AST for a CEL expression description: | Retrieves the visual AST for a CEL expression. ##### Permissions Must have the `manage_system` permission. operationId: GetCELVisualAST requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CELExpression" responses: "200": description: Visual AST retrieved successfully. content: application/json: schema: $ref: "#/components/schemas/VisualExpression" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "500": $ref: "#/components/responses/InternalServerError" /api/v4/access_control_policies/activate: put: tags: - access control summary: Activate or deactivate access control policies description: | Updates the active status of access control policies. ##### Permissions Must have the `manage_system` permission. OR be a channel admin with manage_channel_access_rules permission for the specified channels. operationId: UpdateAccessControlPoliciesActive requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AccessControlPolicyActiveUpdateRequest" responses: "200": description: Access control policies active status updated successfully. content: application/json: schema: $ref: "#/components/schemas/AccessControlPolicy" "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/content_flagging/flag/config: get: summary: Get content flagging configuration description: | Returns the configuration for content flagging, including the list of available reasons for flagging content. This data is used to gather details from the user when they flag content. An enterprise advanced license is required. tags: - Content Flagging responses: '200': description: Configuration retrieved successfully content: application/json: schema: type: object properties: reasons: type: array items: type: string description: List of reasons for flagging content reporter_comment_required: type: boolean description: Indicates if a comment from the reporter is required when flagging content '404': description: Feature is disabled via the feature flag. '500': description: Internal server error. '501': description: Feature is disabled either via config or an Enterprise Advanced license is not available. /api/v4/content_flagging/team/{team_id}/status: get: summary: Get content flagging status for a team description: | Returns the content flagging status for a specific team, indicating whether content flagging is enabled on the specified team or not. An enterprise advanced license is required. tags: - Content Flagging parameters: - in: path name: team_id required: true schema: type: string description: The ID of the team to retrieve the content flagging status for responses: '200': description: Content flagging status retrieved successfully content: application/json: schema: type: object properties: enabled: type: boolean description: Indicates if content flagging is enabled for the team '403': description: Forbidden - User does not have permission to access this team. '404': description: The specified team was not found or the feature is disabled via the feature flag. '500': description: Internal server error. '501': description: Feature is disabled either via config or an Enterprise Advanced license is not available. /api/v4/content_flagging/post/{post_id}/flag: post: summary: Flag a post description: | Flags a post with a reason and a comment. The user must have access to the channel to which the post belongs to. An enterprise advanced license is required. tags: - Content Flagging parameters: - in: path name: post_id required: true schema: type: string description: The ID of the post to be flagged requestBody: required: true content: application/json: schema: type: object properties: reason: type: string description: The reason for flagging the post. This must be one of the configured reasons available for selection. comment: type: string description: Comment from the user flagging the post. responses: "200": description: Post flagged successfully content: application/json: schema: $ref: "#/components/schemas/StatusOK" '400': description: Bad request - Invalid input data or missing required fields. '403': description: Forbidden - User does not have permission to flag this post. '404': description: Post not found or feature is disabled via the feature flag. '500': description: Internal server error. '501': description: Feature is disabled either via config or an Enterprise Advanced license is not available. /api/v4/content_flagging/fields: get: summary: Get content flagging property fields description: | Returns the list of property fields that can be associated with content flagging reports. These fields are used for storing metadata about a post's flag. An enterprise advanced license is required. tags: - Content Flagging responses: '200': description: Custom fields retrieved successfully content: application/json: schema: type: object description: A map of property field names to their definitions additionalProperties: $ref: "#/components/schemas/PropertyField" '404': description: Feature is disabled via the feature flag. '500': description: Internal server error. '501': description: Feature is disabled either via config or an Enterprise Advanced license is not available. /api/v4/content_flagging/post/{post_id}/field_values: get: summary: Get content flagging property field values for a post description: | Returns the property field values associated with content flagging reports for a specific post. These values provide additional context about the flags on the post. An enterprise advanced license is required. tags: - Content Flagging parameters: - in: path name: post_id required: true schema: type: string description: The ID of the post to retrieve property field values for responses: '200': description: Property field values retrieved successfully content: application/json: schema: type: array items: $ref: "#/components/schemas/PropertyValue" description: An array of property field values associated with the post '403': description: Forbidden - User does not have permission to access this post. '404': description: Post not found or feature is disabled via the feature flag. '500': description: Internal server error. '501': description: Feature is disabled either via config or an Enterprise Advanced license is not available. /api/v4/content_flagging/post/{post_id}: get: summary: Get a flagged post with all its content. description: | Returns the flagged post with all its data, even if it is soft-deleted. This endpoint is only accessible by content reviewers. A content reviewer can only fetch flagged posts from this API if the post is indeed flagged and they are a content reviewer of the post's team. An enterprise advanced license is required. tags: - Content Flagging parameters: - in: path name: post_id required: true schema: type: string description: The ID of the post to retrieve responses: '200': description: The flagged post is fetched correctly content: application/json: schema: $ref: "#/components/schemas/Post" '403': description: Forbidden - User does not have permission to access this post, or is not a reviewer of the post's team. '404': description: Post not found or feature is disabled via the feature flag. '500': description: Internal server error. '501': description: Feature is disabled either via config or an Enterprise Advanced license is not available. /api/v4/content_flagging/post/{post_id}/remove: put: summary: Remove a flagged post description: | Permanently removes a flagged post and all its associated contents from the system. This action is typically performed by content reviewers after they have reviewed the flagged content. This action is irreversible. The user must be a content reviewer of the team to which the post belongs to. An enterprise advanced license is required. tags: - Content Flagging parameters: - in: path name: post_id required: true schema: type: string description: The ID of the post to be removed responses: '200': description: Post removed successfully content: application/json: schema: $ref: "#/components/schemas/StatusOK" '403': description: Forbidden - User does not have permission to remove this post. '404': description: Post not found or feature is disabled via the feature flag. '500': description: Internal server error. '501': description: Feature is disabled either via config or an Enterprise Advanced license is not available. /api/v4/content_flagging/post/{post_id}/keep: put: summary: Keep a flagged post description: | Marks a flagged post as reviewed and keeps it in the system without any changes. This action is typically performed by content reviewers after they have reviewed the flagged content and determined that it does not violate any guidelines. The user must be a content reviewer of the team to which the post belongs to. An enterprise advanced license is required. tags: - Content Flagging parameters: - in: path name: post_id required: true schema: type: string description: The ID of the post to be kept responses: '200': description: Post marked to be kept successfully content: application/json: schema: $ref: "#/components/schemas/StatusOK" '403': description: Forbidden - User does not have permission to keep this post. '404': description: Post not found or feature is disabled via the feature flag. '500': description: Internal server error. '501': description: Feature is disabled either via config or an Enterprise Advanced license is not available. /api/v4/content_flagging/config: get: summary: Get the system content flagging configuration description: | Returns the system configuration for content flagging, including settings related to notifications, flagging configurations, etc.. Only system admins can access this endpoint. tags: - Content Flagging responses: '200': description: Configuration retrieved successfully content: application/json: schema: $ref: "#/components/schemas/ContentFlaggingConfig" '404': description: Feature is disabled via the feature flag. '500': description: Internal server error. '403': description: User does not have permission to manage system configuration. put: summary: Update the system content flagging configuration description: | Updates the system configuration for content flagging, including settings related to notifications, flagging configurations, etc.. Only system admins can access this endpoint. tags: - Content Flagging requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ContentFlaggingConfig" responses: '200': description: Configuration updated successfully '400': description: Bad request - Invalid input data or missing required fields. '404': description: Feature is disabled via the feature flag. '500': description: Internal server error. '403': description: User does not have permission to manage system configuration. /api/v4/content_flagging/team/{team_id}/reviewers/search: get: summary: Search content reviewers in a team description: | Searches for content reviewers of a specific team based on a provided term. Only a content reviewer can access this endpoint. An enterprise advanced license is required. tags: - Content Flagging parameters: - in: path name: team_id required: true schema: type: string description: The ID of the team to search for content reviewers for - in: query name: term required: true schema: type: string description: The search term to filter content reviewers by responses: '200': description: Content reviewers retrieved successfully content: application/json: schema: type: array items: $ref: "#/components/schemas/User" description: An array of user objects representing the content reviewers that match the search criteria '403': description: Forbidden - User does not have permission to access this team. '404': description: The specified team was not found or the feature is disabled via the feature flag. '500': description: Internal server error. '501': description: Feature is disabled either via config or an Enterprise Advanced license is not available. /api/v4/content_flagging/post/{post_id}/assign/{content_reviewer_id}: post: summary: Assign a content reviewer to a flagged post description: | Assigns a content reviewer to a specific flagged post for review. The user must be a content reviewer of the team to which the post belongs to. An enterprise advanced license is required. tags: - Content Flagging parameters: - in: path name: post_id required: true schema: type: string description: The ID of the post to assign a content reviewer to - in: path name: content_reviewer_id required: true schema: type: string description: The ID of the user to be assigned as the content reviewer for the post responses: '200': description: Content reviewer assigned successfully content: application/json: schema: $ref: "#/components/schemas/StatusOK" '400': description: Bad request - Invalid input data or missing required fields. '403': description: Forbidden - User does not have permission to assign a reviewer to this post. '404': description: Post or user not found, or feature is disabled via the feature flag. '500': description: Internal server error. '501': description: Feature is disabled either via config or an Enterprise Advanced license is not available. /api/v4/agents: get: tags: - agents summary: Get available agents description: > Retrieve all available agents from the plugin's bridge API. If a user ID is provided, only agents accessible to that user are returned. ##### Permissions Must be authenticated. __Minimum server version__: 11.2 operationId: GetAgents responses: "200": description: Agents retrieved successfully content: application/json: schema: $ref: "#/components/schemas/AgentsResponse" "401": $ref: "#/components/responses/Unauthorized" "500": $ref: "#/components/responses/InternalServerError" /api/v4/llmservices: get: tags: - agents summary: Get available LLM services description: > Retrieve all available LLM services from the plugin's bridge API. If a user ID is provided, only services accessible to that user (via their permitted bots) are returned. ##### Permissions Must be authenticated. __Minimum server version__: 11.2 operationId: GetLLMServices responses: "200": description: LLM services retrieved successfully content: application/json: schema: $ref: "#/components/schemas/ServicesResponse" "401": $ref: "#/components/responses/Unauthorized" "500": $ref: "#/components/responses/InternalServerError" components: securitySchemes: bearerAuth: type: http scheme: bearer responses: 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 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" PropertyField: type: object properties: id: type: string group_id: type: string name: type: string type: type: string attrs: type: object target_id: type: string target_type: type: string create_at: type: integer format: int64 update_at: type: integer format: int64 delete_at: type: integer format: int64 PropertyFieldPatch: type: object properties: name: type: string type: type: string attrs: type: object target_id: type: string target_type: type: string PropertyValue: type: object properties: id: type: string target_id: type: string target_type: type: string group_id: type: string field_id: type: string value: type: string create_at: type: integer format: int64 update_at: type: integer format: int64 delete_at: type: integer format: int64 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 LdapSettings: type: object properties: Enable: type: boolean EnableSync: type: boolean LdapServer: type: string LdapPort: type: integer ConnectionSecurity: type: string BaseDN: type: string BindUsername: type: string BindPassword: type: string MaximumLoginAttempts: type: integer UserFilter: type: string GroupFilter: type: string GuestFilter: type: string EnableAdminFilter: type: boolean AdminFilter: type: string GroupDisplayNameAttribute: type: string GroupIdAttribute: type: string FirstNameAttribute: type: string LastNameAttribute: type: string EmailAttribute: type: string UsernameAttribute: type: string NicknameAttribute: type: string IdAttribute: type: string PositionAttribute: type: string LoginIdAttribute: type: string PictureAttribute: type: string SyncIntervalMinutes: type: integer SkipCertificateVerification: type: boolean PublicCertificateFile: type: string PrivateKeyFile: type: string QueryTimeout: type: integer MaxPageSize: type: integer LoginFieldName: type: string LoginButtonColor: type: string LoginButtonBorderColor: type: string LoginButtonTextColor: type: string LdapDiagnosticResult: type: object properties: test_name: type: string description: Name/type of the diagnostic test being performed test_value: type: string description: The actual test value (filter string or attribute name) total_count: type: integer description: Number of entries found by the filter message: type: string description: Optional success/info message error: type: string description: Optional error message if test failed sample_results: type: array description: Array of sample LDAP entries found items: type: object properties: dn: type: string description: Distinguished Name username: type: string description: Username email: type: string description: Email first_name: type: string description: First name last_name: type: string description: Last name id: type: string description: ID attribute display_name: type: string description: Display name for groups available_attributes: type: object description: Map of all available LDAP attributes additionalProperties: 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 AmazonS3StorageClass: type: string 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 ReportAProblemType: type: string ReportAProblemMail: type: string AllowDownloadLogs: type: boolean 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 AmazonS3StorageClass: type: string 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 ReportAProblemType: type: boolean ReportAProblemMail: type: boolean AllowDownloadLogs: 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 IntuneLoginRequest: type: object description: Request body for Microsoft Intune MAM authentication using Azure AD/Entra ID access token required: - access_token properties: access_token: type: string description: Microsoft Entra ID access token obtained via MSAL (Microsoft Authentication Library). This token must be scoped to the Intune MAM app registration and will be validated against the configured tenant. device_id: type: string description: Optional mobile device identifier used for push notifications. If provided, the device will be registered for receiving push notifications. 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: array properties: items: type: object properties: id: description: The unique ID for the node type: string version: description: The server version the node is on type: string schema_version: description: The number of the latest DB migration successfully executed for the node type: string config_hash: description: The hash of the configuration file the node is using type: string ipaddress: description: The IP address of the node type: string hostname: description: The hostname for this node type: string 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 ClientRegistrationRequest: type: object description: OAuth 2.0 Dynamic Client Registration request as defined in RFC 7591 required: - redirect_uris properties: redirect_uris: type: array items: type: string description: Array of redirection URI strings for use in redirect-based flows such as the authorization code and implicit flows minItems: 1 client_name: type: string description: Human-readable string name of the client to be presented to the end-user during authorization maxLength: 64 client_uri: type: string description: URL string of a web page providing information about the client maxLength: 256 format: uri ClientRegistrationResponse: type: object description: OAuth 2.0 Dynamic Client Registration response as defined in RFC 7591 properties: client_id: type: string description: OAuth 2.0 client identifier string client_secret: type: string description: OAuth 2.0 client secret string redirect_uris: type: array items: type: string description: Array of the registered redirection URI strings token_endpoint_auth_method: type: string description: String indicator of the requested authentication method for the token endpoint enum: - client_secret_post - none grant_types: type: array items: type: string description: Array of OAuth 2.0 grant type strings that the client can use at the token endpoint response_types: type: array items: type: string description: Array of the OAuth 2.0 response type strings that the client can use at the authorization endpoint scope: type: string description: Space-separated list of scope values that the client can use when requesting access tokens client_name: type: string description: Human-readable string name of the client to be presented to the end-user during authorization client_uri: type: string description: URL string of a web page providing information about the client format: uri AuthorizationServerMetadata: type: object description: OAuth 2.0 Authorization Server Metadata as defined in RFC 8414 properties: issuer: type: string description: The authorization server's issuer identifier, which is a URL that uses the "https" scheme authorization_endpoint: type: string description: URL of the authorization server's authorization endpoint token_endpoint: type: string description: URL of the authorization server's token endpoint response_types_supported: type: array items: type: string description: JSON array containing a list of the OAuth 2.0 response_type values that this authorization server supports registration_endpoint: type: string description: URL of the authorization server's OAuth 2.0 Dynamic Client Registration endpoint scopes_supported: type: array items: type: string description: JSON array containing a list of the OAuth 2.0 scope values that this authorization server supports grant_types_supported: type: array items: type: string description: JSON array containing a list of the OAuth 2.0 grant type values that this authorization server supports token_endpoint_auth_methods_supported: type: array items: type: string description: JSON array containing a list of client authentication methods supported by the token endpoint code_challenge_methods_supported: type: array items: type: string description: JSON array containing a list of PKCE code challenge methods supported by this authorization server required: - issuer - response_types_supported 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. auto_responder_message: type: string description: The message sent to users when they are auto-responded to. Defaults to "". push_threads: type: string description: Set to "all" to enable mobile push notifications for followed threads and "none" to disable. Defaults to "all". comments: type: string description: Set to "any" to enable notifications for comments to any post you have replied to, "root" for comments on your posts, and "never" to disable. Only affects users with collapsed reply threads disabled. Defaults to "never". desktop_threads: type: string description: Set to "all" to enable desktop notifications for followed threads and "none" to disable. Defaults to "all". email_threads: type: string description: Set to "all" to enable email notifications for followed threads and "none" to disable. Defaults to "all". Timezone: type: object properties: useAutomaticTimezone: type: string 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" nullable: true files: $ref: "#/components/schemas/FilesLimits" nullable: true integrations: $ref: "#/components/schemas/IntegrationsLimits" nullable: true messages: $ref: "#/components/schemas/MessagesLimits" nullable: true teams: $ref: "#/components/schemas/TeamsLimits" nullable: true 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 GroupMember: type: object properties: group_id: type: string user_id: type: string create_at: type: integer format: int64 delete_at: type: integer format: int64 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 RemoteCluster: type: object properties: remote_id: type: string remote_team_id: type: string name: type: string display_name: type: string site_url: description: URL of the remote cluster type: string default_team_id: description: The team where channels from invites are created type: string create_at: description: Time in milliseconds that the remote cluster was created type: integer delete_at: description: Time in milliseconds that the remote cluster record was deleted type: integer last_ping_at: description: Time in milliseconds when the last ping to the remote cluster was run type: integer token: type: string remote_token: type: string topics: type: string creator_id: type: string plugin_id: type: string options: description: A bitmask with a set of option flags type: integer 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 SharedChannelRemote: type: object properties: id: description: The id of the shared channel remote type: string channel_id: description: The id of the channel type: string creator_id: description: Id of the user that invited the remote to share the channel type: string create_at: description: Time in milliseconds that the remote was invited to the channel type: integer update_at: description: Time in milliseconds that the shared channel remote record was last updated type: integer delete_at: description: Time in milliseconds that the shared chanenl remote record was deleted type: integer is_invite_accepted: description: Indicates if the invite has been accepted by the remote type: boolean is_invite_confirmed: description: Indicates if the invite has been confirmed by the remote type: boolean remote_id: description: Id of the remote cluster that the channel is shared with type: string last_post_update_at: description: Time in milliseconds of the last post in the channel that was synchronized with the remote update_at type: integer last_post_id: description: Id of the last post in the channel that was synchronized with the remote type: string last_post_create_at: description: Time in milliseconds of the last post in the channel that was synchronized with the remote create_at type: string last_post_create_id: type: string 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 BridgeAgentInfo: type: object properties: id: type: string description: Unique identifier for the agent displayName: type: string description: Human-readable name for the agent username: type: string description: Username associated with the agent bot service_id: type: string description: ID of the service providing this agent service_type: type: string description: Type of the service (e.g., openai, anthropic) BridgeServiceInfo: type: object properties: id: type: string description: Unique identifier for the LLM service name: type: string description: Name of the LLM service type: type: string description: Type of the service (e.g., openai, anthropic, azure) AgentsResponse: type: object properties: agents: type: array items: $ref: "#/components/schemas/BridgeAgentInfo" description: List of available agents ServicesResponse: type: object properties: services: type: array items: $ref: "#/components/schemas/BridgeServiceInfo" description: List of available LLM services 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 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 auth_data: type: string auth_service: type: string email: type: string nickname: type: string first_name: type: string last_name: type: string position: type: string roles: type: string locale: type: string timezone: $ref: "#/components/schemas/Timezone" disable_welcome_email: type: boolean last_login: 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 MessageDescriptor: type: object properties: id: description: The i18n message ID type: string defaultMessage: description: The default message text type: string values: description: Optional values for message interpolation type: object additionalProperties: true PreviewModalContentData: type: object properties: skuLabel: $ref: "#/components/schemas/MessageDescriptor" title: $ref: "#/components/schemas/MessageDescriptor" subtitle: $ref: "#/components/schemas/MessageDescriptor" videoUrl: description: URL of the video content type: string videoPoster: description: URL of the video poster/thumbnail image type: string useCase: description: The use case category for this content type: string ServerLimits: 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 # Outgoing OAuth Connections 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 ScheduledPost: type: object properties: id: type: string create_at: description: The time in milliseconds a scheduled post was created type: integer format: int64 update_at: description: The time in milliseconds a scheduled post was last updated type: integer format: int64 user_id: type: string channel_id: type: string root_id: type: string message: type: string props: type: object file_ids: type: array items: type: string scheduled_at: description: The time in milliseconds a scheduled post is scheduled to be sent at type: integer format: int64 processed_at: description: The time in milliseconds a scheduled post was processed at type: integer format: int64 error_code: type: string description: Explains the error behind why a scheduled post could not have been sent metadata: $ref: "#/components/schemas/PostMetadata" AccessControlFieldsAutocompleteResponse: type: object properties: fields: type: array items: type: object properties: name: type: string description: The name of the field. description: type: string description: A description of the field. AccessControlPoliciesWithCount: type: object properties: policies: type: array items: $ref: "#/components/schemas/AccessControlPolicy" total_count: type: integer description: The total number of policies. AccessControlPolicy: type: object properties: id: type: string description: The unique identifier of the policy. name: type: string description: The unique name for the policy. display_name: type: string description: The human-readable name for the policy. description: type: string description: A description of the policy. expression: type: string description: The CEL expression defining the policy rules. is_active: type: boolean description: Whether the policy is currently active and enforced. create_at: type: integer format: int64 description: The time in milliseconds the policy was created. update_at: type: integer format: int64 description: The time in milliseconds the policy was last updated. delete_at: type: integer format: int64 description: The time in milliseconds the policy was deleted. AccessControlPolicySearch: type: object properties: term: type: string description: The search term to match against policy names or display names. type: type: string description: The type of policy (e.g., 'parent' or 'channel'). parent_id: type: string description: The ID of the parent policy to search within. ids: type: array items: type: string description: List of policy IDs to filter by. active: type: boolean description: Filter policies by active status. include_children: type: boolean description: Whether to include child policies in the result. cursor: $ref: "#/components/schemas/AccessControlPolicyCursor" limit: type: integer description: The maximum number of policies to return. AccessControlPolicyCursor: type: object properties: id: type: string description: The ID of the policy to start searching after. AccessControlPolicyTestResponse: type: object properties: users: type: array items: $ref: "#/components/schemas/User" description: A list of users affected by the policy expression. total_count: type: integer description: The total number of users affected. ChannelSearch: # Added based on dataretention.yaml and access_control.go usage 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. private: type: boolean description: Filters results to only return Private channels. deleted: type: boolean description: Filters results to only return deleted / archived channels. include_deleted: type: boolean description: Whether to include deleted channels in the search results. # Add other potential search fields like not_associated_to_group, exclude_default_channels etc. ChannelsWithCount: # Added based on access_control.go usage type: object properties: channels: $ref: "#/components/schemas/ChannelListWithTeamData" # Referencing existing type used in similar contexts total_count: type: integer description: The total number of channels. ExpressionError: type: object properties: message: type: string description: The error message. field: type: string description: The field related to the error, if applicable. line: type: integer description: The line number where the error occurred in the expression. column: type: integer description: The column number where the error occurred in the expression. QueryExpressionParams: type: object properties: expression: type: string description: The policy expression to test. term: type: string description: A search term to filter users against whom the expression is tested. limit: type: integer description: The maximum number of users to return. after: type: string description: The ID of the user to start the test after (for pagination). channelId: type: string description: The channel ID to contextually test the expression against (required for channel admins). CELExpression: type: object properties: expression: type: string description: The CEL expression to visualize. channelId: type: string description: The channel ID to contextually test the expression against (required for channel admins). VisualExpression: type: object properties: conditions: type: array items: $ref: "#/components/schemas/Condition" description: The visual AST for the CEL expression Condition: type: object properties: attribute: type: string description: The attribute name. operator: type: string description: The operator of a single condition. value: type: string description: The value. value_type: type: string description: The value type. ChannelBanner: type: object properties: enabled: type: boolean description: enabled indicates whether the channel banner is enabled or not text: type: string description: text is the actual text that renders in the channel banner. Markdown is supported. background_color: type: string description: background_color is the HEX color code for the banner's background ContentFlaggingConfig: type: object properties: EnableContentFlagging: type: boolean description: Flag to enable or disable content flagging feature example: true NotificationSettings: $ref: '#/components/schemas/NotificationSettings' AdditionalSettings: $ref: '#/components/schemas/AdditionalSettings' ReviewerSettings: $ref: '#/components/schemas/ReviewerSettings' NotificationSettings: type: object properties: EventTargetMapping: $ref: '#/components/schemas/EventTargetMapping' required: - EventTargetMapping EventTargetMapping: type: object properties: assigned: type: array items: type: string description: List of targets to notify when content is assigned example: [ ] dismissed: type: array items: type: string description: List of targets to notify when content is dismissed example: [ ] flagged: type: array items: type: string description: List of targets to notify when content is flagged example: [ "reviewers" ] removed: type: array items: type: string description: List of targets to notify when content is removed example: [ ] required: - assigned - dismissed - flagged - removed AdditionalSettings: type: object properties: Reasons: type: array items: type: string description: Predefined reasons for flagging content example: [ "reason 1", "reason 2", "reason 3" ] ReporterCommentRequired: type: boolean description: Whether a comment is required from the reporter example: false ReviewerCommentRequired: type: boolean description: Whether a comment is required from the reviewer example: false HideFlaggedContent: type: boolean description: Whether to hide flagged content from general view example: true required: - Reasons - ReporterCommentRequired - ReviewerCommentRequired - HideFlaggedContent ReviewerSettings: type: object properties: CommonReviewers: type: boolean description: Whether to use common reviewers across all teams example: true SystemAdminsAsReviewers: type: boolean description: Whether system administrators can act as reviewers example: false TeamAdminsAsReviewers: type: boolean description: Whether team administrators can act as reviewers example: true CommonReviewerIds: type: array items: type: string description: List of user IDs designated as common reviewers example: [ "onymzj7qcjnz7dcnhtjp1noc3w" ] TeamReviewersSetting: type: object additionalProperties: $ref: '#/components/schemas/TeamReviewerConfig' description: Team-specific reviewer configuration, keyed by team ID example: "8guxic3sg7nijeu5dgxt1fh4ia": Enabled: true ReviewerIds: [ ] "u1ujk34a47gfxp856pdczs9gey": Enabled: false ReviewerIds: [ ] required: - CommonReviewers - SystemAdminsAsReviewers - TeamAdminsAsReviewers - CommonReviewerIds - TeamReviewersSetting TeamReviewerConfig: type: object properties: Enabled: type: boolean description: Whether team-specific reviewers are enabled for this team example: true ReviewerIds: type: array items: type: string description: List of user IDs designated as reviewers for this specific team example: [ ] required: - Enabled - ReviewerIds AccessControlPolicyActiveUpdateRequest: type: object properties: entries: type: array items: $ref: "#/components/schemas/AccessControlPolicyActiveUpdate" AccessControlPolicyActiveUpdate: type: object properties: id: type: string description: The ID of the policy. active: type: boolean description: The active status of the policy. externalDocs: description: Find out more about Mattermost url: 'https://about.mattermost.com' security: - bearerAuth: []