{
"openapi": "3.0.0",
"info": {
"description": "There is also a work-in-progress [Postman API reference](https://documenter.getpostman.com/view/4508214/RW8FERUn).\n",
"version": "4.0.0",
"title": "Mattermost API Reference",
"termsOfService": "https://about.mattermost.com/default-terms/",
"contact": {
"email": "feedback@mattermost.com"
},
"x-logo": {
"url": "https://www.mattermost.org/wp-content/uploads/2016/03/logoHorizontal_WS.png",
"backgroundColor": "#FFFFFF"
}
},
"tags": [
{
"name": "introduction",
"description": "The Mattermost Web Services API is used by Mattermost clients and third party applications to interact with the server. [JavaScript and Golang drivers for](/#tag/drivers) connecting to the APIs are also available.\n\n### Support\n\nMattermost core committers work with the community to keep the API documentation up-to-date.\n\nIf you have questions on API routes not listed in this reference, please [join the Mattermost community server](https://pre-release.mattermost.com/signup_user_complete/?id=f1924a8db44ff3bb41c96424cdc20676) to ask questions in the Developers channel, [or post questions to our Developer Discussion forum](http://forum.mattermost.org/c/dev).\n\n[Bug reports](https://github.com/mattermost/mattermost-api-reference/issues) in the documentation or the API are also welcome, as are pull requests to fix the issues.\n\n### Contributing\n\nWhen 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 changes](https://github.com/mattermost/mattermost-api-reference/commit/d574c0c1e95dc2228dc96663afd562f1305e3ece) and [larger changes](https://github.com/mattermost/mattermost-api-reference/commit/1ae3314f0935eebba8c885d8969dcad72f801501) are all welcome.\n\nWe also have [Help Wanted tickets](https://github.com/mattermost/mattermost-api-reference/issues) 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).\n\nThe source code for this API reference is hosted at https://github.com/mattermost/mattermost-api-reference.\n"
},
{
"name": "schema",
"description": "All API access is through HTTP(S) requests at `your-mattermost-url.com/api/v4`. All request and response bodies are `application/json`.\n\nWhen 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.\n"
},
{
"name": "drivers",
"description": "The easiest way to interact with the Mattermost Web Service API is through a language specific driver.\n\n#### Official Drivers\n* [Mattermost JavaScript Driver](https://github.com/mattermost/mattermost-redux/blob/master/src/client/client4.ts)\n* [Mattermost Golang Driver](https://github.com/mattermost/mattermost-server/blob/master/model/client4.go)\n\n#### Community-built Drivers\n* [PHP Driver](https://github.com/gnello/php-mattermost-driver) - built by [@gnello](https://github.com/gnello) and [@prixone](https://github.com/prixone)\n* [Python Driver](https://github.com/Vaelor/python-mattermost-driver) - built by [@Vaelor](https://github.com/Vaelor)\n\nFor other community-built drivers and API wrappers, see [our app directory](https://about.mattermost.com/community-applications/#privateApps).\n"
},
{
"name": "authentication",
"description": "There are multiple ways to authenticate against the Mattermost API.\n\nAll examples assume there is a Mattermost instance running at http://localhost:8065.\n\n#### Session Token\n\nMake an HTTP POST to `your-mattermost-url.com/api/v4/users/login` with a JSON body indicating the user’s `login_id`, `password` and optionally the MFA `token`. The `login_id` can be an email, username or an AD/LDAP ID depending on the system's configuration.\n\n```\ncurl -i -d '{\"login_id\":\"someone@nowhere.com\",\"password\":\"thisisabadpassword\"}' http://localhost:8065/api/v4/users/login\n```\n\nNOTE: 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:\n\n```\ncurl -i -d \"{\\\"login_id\\\":\\\"someone@nowhere.com\\\",\\\"password\\\":\\\"thisisabadpassword\\\"}\" http://localhost:8065/api/v4/users/login\n```\n\nIf successful, the response will contain a `Token` header and a user object in the body.\n\n```\nHTTP/1.1 200 OK\nSet-Cookie: MMSID=hyr5dmb1mbb49c44qmx4whniso; Path=/; Max-Age=2592000; HttpOnly\nToken: hyr5dmb1mbb49c44qmx4whniso\nX-Ratelimit-Limit: 10\nX-Ratelimit-Remaining: 9\nX-Ratelimit-Reset: 1\nX-Request-Id: smda55ckcfy89b6tia58shk5fh\nX-Version-Id: developer\nDate: Fri, 11 Sep 2015 13:21:14 GMT\nContent-Length: 657\nContent-Type: application/json; charset=utf-8\n\n{{user object as json}}\n```\n\nInclude the `Token` as part of the `Authorization` header on your future API requests with the `Bearer` method.\n\n```\ncurl -i -H 'Authorization: Bearer hyr5dmb1mbb49c44qmx4whniso' http://localhost:8065/api/v4/users/me\n```\n\nYou should now be able to access the API as the user you logged in as.\n\n#### Personal Access Tokens\n\nUsing [personal access tokens](https://docs.mattermost.com/developer/personal-access-tokens.html) is very similar to using a session token. The only real difference is that session tokens will expire, while personal access tokens will live until they are manually revoked by the user or an admin.\n\nJust 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.\n\n```\ncurl -i -H 'Authorization: Bearer 9xuqwrwgstrb3mzrxb83nb357a' http://localhost:8065/api/v4/users/me\n```\n\n#### OAuth 2.0\n\nMattermost has the ability to act as an [OAuth 2.0](https://tools.ietf.org/html/rfc6749) service provider.\n\nThe official documentation for [using your Mattermost server as an OAuth 2.0 service provider can be found here.](https://docs.mattermost.com/developer/oauth-2-0-applications.html)\n\nFor an example on how to register an OAuth 2.0 app with your Mattermost instance, please see the [Mattermost-Zapier integration documentation](https://docs.mattermost.com/integrations/zapier.html#register-zapier-as-an-oauth-2-0-application).\n"
},
{
"name": "errors",
"description": "All errors will return an appropriate HTTP response code along with the following JSON body:\n```\n{\n \"id\": \"the.error.id\",\n \"message\": \"Something went wrong\", // the reason for the error\n \"request_id\": \"\", // the ID of the request\n \"status_code\": 0, // the HTTP status code\n \"is_oauth\": false // whether the error is OAuth specific\n}\n```\n"
},
{
"name": "rate limiting",
"description": "Whenever you make an HTTP request to the Mattermost API you might notice the following headers included in the response:\n```\nX-Ratelimit-Limit: 10\nX-Ratelimit-Remaining: 9\nX-Ratelimit-Reset: 1441983590\n```\n\nThese headers are telling you your current rate limit status.\n\n| Header | Description |\n| ------ | ----------- |\n| X-Ratelimit-Limit | The maximum number of requests you can make per second. |\n| X-Ratelimit-Remaining | The number of requests remaining in the current window. |\n| X-Ratelimit-Reset | The remaining UTC epoch seconds before the rate limit resets. |\n\nIf you exceed your rate limit for a window you will receive the following error in the body of the response:\n\n```\nHTTP/1.1 429 Too Many Requests\nDate: Tue, 10 Sep 2015 11:20:28 GMT\nX-RateLimit-Limit: 10\nX-RateLimit-Remaining: 0\nX-RateLimit-Reset: 1\n\nlimit exceeded\n```\n"
},
{
"name": "WebSocket",
"description": "In addition to the HTTP RESTful web service, Mattermost also offers a WebSocket event delivery system and some API functionality.\n\nTo 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.\n\n#### Authentication\n\nThe Mattermost WebSocket can be authenticated by cookie 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.\n\nTo authenticate with an authentication challenge, first connect the WebSocket and then send the following JSON over the connection:\n\n```\n{\n \"seq\": 1,\n \"action\": \"authentication_challenge\",\n \"data\": {\n \"token\": \"mattermosttokengoeshere\"\n }\n}\n```\n\nIf successful, you will receive a standard OK response over the WebSocket connection:\n\n```\n{\n \"status\": \"OK\",\n \"seq_reply\": 1\n}\n```\n\nOnce successfully authenticated, the server will pass a `hello` WebSocket event containing server version over the connection.\n\n#### Events\n\nWebSocket 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.\n\nEvents on the WebSocket will have the form:\n\n```\n{\n \"event\": \"hello\",\n \"data\": {\n \"server_version\": \"3.6.0.1451.1c38da627ebb4e3635677db6939e9195\"\n },\n \"broadcast\":{\n \"omit_users\": null,\n \"user_id\": \"ay5sq51sebfh58ktrce5ijtcwy\",\n \"channel_id\": \"\",\n \"team_id\": \"\"\n },\n \"seq\": 0\n}\n```\n\nThe `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.\n\nThe list of Mattermost WebSocket events are:\n- added_to_team\n- authentication_challenge\n- channel_converted\n- channel_created\n- channel_deleted\n- channel_member_updated\n- channel_updated\n- channel_viewed\n- config_changed\n- delete_team\n- direct_added\n- emoji_added\n- ephemeral_message\n- group_added\n- hello\n- leave_team\n- license_changed\n- memberrole_updated\n- new_user\n- plugin_disabled\n- plugin_enabled\n- plugin_statuses_changed\n- post_deleted\n- post_edited\n- post_unread\n- posted\n- preference_changed\n- preferences_changed\n- preferences_deleted\n- reaction_added\n- reaction_removed\n- response\n- role_updated\n- status_change\n- typing\n- update_team\n- user_added\n- user_removed\n- user_role_updated\n- user_updated\n- dialog_opened\n- thread_updated\n- thread_follow_changed\n- thread_read_changed\n\n#### WebSocket API\n\nMattermost has some basic support for WebSocket APIs. A connected WebSocket can make requests by sending the following over the connection:\n\n```\n{\n \"action\": \"user_typing\",\n \"seq\": 2,\n \"data\": {\n \"channel_id\": \"nhze199c4j87ped4wannrjdt9c\",\n \"parent_id\": \"\"\n }\n}\n```\n\nThis 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.\n\nThe `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:\n\n```\n{\n \"status\": \"OK\",\n \"seq_reply\": 2\n}\n```\n\nNotice `seq_reply` is 2, matching the `seq` of the original request. Using this a client can distinguish which request the response is meant for.\n\nIf there was any information to respond with, it would be encapsulated in a `data` field.\n\nIn the case of an error, the response would be:\n\n```\n{\n \"status\": \"FAIL\",\n \"seq_reply\": 2,\n \"error\": {\n \"id\": \"some.error.id.here\",\n \"message\": \"Some error message here\"\n }\n}\n```\n\nThe list of WebSocket API actions is:\n- user_typing\n- get_statuses\n- get_statuses_by_ids\n\nTo see how these actions work, please refer to either the [Golang WebSocket driver](https://github.com/mattermost/mattermost-server/blob/master/model/websocket_client.go) or our [JavaScript WebSocket driver](https://github.com/mattermost/mattermost-redux/blob/master/src/client/websocket_client.ts).\n"
},
{
"name": "APIv3 Deprecation",
"description": "Since Mattermost 4.6 released on January 16, 2018, API v3 has no longer been supported and it will be removed in Mattermost Server v5.0 on June 16, 2018. Follow these simple steps to migrate your integrations and apps to API v4. Otherwise your integrations may break once you upgrade to Mattermost 5.0\n\n1. Set your server's log level to `DEBUG` in **System Console > General > Logging > File Log Level** to print detailed logs for API requests.\n2. In **System Console > Logs**, search for requests hitting `/api/v3/` endpoints. Any requests hitting these endpoints are from integrations that should be migrated to API v4.\n - For in-house or self-built integrations, update them to use v4 with the help of [this API reference](https://api.mattermost.com). Most v3 endpoints have direct counterparts in v4 and should be migrated easily.\n - For third-party integrations, visit their homepage (on GitHub, GitLab, etc.). Check if they already have a version that uses the Mattermost v4 API. If they do not, consider opening an issue asking them if support is planned.\n3. Once all integrations have been migrated to API v4, review the server logs with log level set to `DEBUG`. Confirm no requests hit `/api/v3/` endpoints.\n4. Set **Allow use of API v3 endpoints** to `false` in **System Console > General > Configuration**, or set `EnableAPIv3` to `false` in `config.json`. This setting disables API v3 on your server. Any time a v3 endpoint is used, an error is logged in **System Console > Logs**.\n5. Set your server's log level back to `ERROR`. Use the error logs to help track down any remaining uses of API v3.\n\nBelow are the major changes made between v3 and v4:\n\n1. Endpoint URLs only require team IDs when necessary. For example, getting a channel by ID no longer requires a team ID in v4.\n2. Collection endpoints now generally return lists and include paging as part of the query string.\n3. User ID is now included in most user endpoints. This allows admins to modify other users through v4 endpoints.\n\nIf you have any questions about the API v3 deprecation, or about migrating from v3 to v4, [join our daily build server at pre-release.mattermost.com](https://pre-release.mattermost.com/signup_user_complete/?id=f1924a8db44ff3bb41c96424cdc20676) and ask questions in the [APIv4 channel](https://pre-release.mattermost.com/core/channels/apiv4).\n"
},
{
"name": "users",
"description": "Endpoints for creating, getting and interacting with users.\n\nWhen 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.\n"
},
{
"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": "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": "OpenGraph",
"description": "Endpoint for getting Open Graph metadata."
},
{
"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."
}
],
"x-tagGroups": [
{
"name": "Overview",
"tags": [
"introduction",
"schema",
"APIv3 Deprecation"
]
},
{
"name": "Standard Features",
"tags": [
"drivers",
"authentication",
"errors",
"rate limiting",
"WebSocket"
]
},
{
"name": "Endpoints",
"tags": [
"users",
"bots",
"teams",
"channels",
"posts",
"threads",
"files",
"uploads",
"preferences",
"status",
"emoji",
"reactions",
"webhooks",
"commands",
"OpenGraph",
"system",
"brand",
"OAuth",
"SAML",
"LDAP",
"groups",
"compliance",
"cluster",
"cloud",
"elasticsearch",
"bleve",
"data retention",
"jobs",
"plugins",
"roles",
"schemes",
"integration_actions",
"shared channels",
"terms of service",
"imports",
"permissions",
"exports"
]
}
],
"servers": [
{
"url": "http://your-mattermost-url.com/api/v4"
},
{
"url": "https://your-mattermost-url.com/api/v4"
}
],
"paths": {
"/users/login": {
"post": {
"tags": [
"users"
],
"summary": "Login to Mattermost server",
"description": "##### Permissions\nNo permission required\n",
"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"
}
}
}
},
"/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.\n##### Permissions\nA Cloud license is required\n",
"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"
}
}
}
},
"/users/logout": {
"post": {
"tags": [
"users"
],
"summary": "Logout from the Mattermost server",
"description": "##### Permissions\nAn active session is required\n",
"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"
}
}
}
},
"/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.\n##### Permissions\nNo permission required but user creation can be controlled by server configuration.\n",
"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"
},
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\n\nuser := &model.User{\n Username: \"username\",\n Email: \"email@domain.com\",\n Password: \"Password1\",\n}\n\ncreatedUser, response := Client.CreateUser(user)\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$resp = $driver->getUserModel()->createUser([\n \"username\" => \"username\",\n \"email\" => \"email@domain.com\",\n \"password\" => \"Password1\"\n]);\n\nif ($resp->getStatusCode() == 200) {\n $createdUser = json_decode($resp->getBody());\n}\n"
}
]
},
"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.\n\nSince 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.\n##### Permissions\nRequires an active session and (if specified) membership to the channel or team being selected from.\n",
"operationId": "GetUsers",
"parameters": [
{
"name": "page",
"in": "query",
"description": "The page to select.",
"schema": {
"type": "integer",
"default": 0
}
},
{
"name": "per_page",
"in": "query",
"description": "The number of users per page. There is a maximum limit of 200 users per page.",
"schema": {
"type": "integer",
"default": 60
}
},
{
"name": "in_team",
"in": "query",
"description": "The ID of the team to get users for.",
"schema": {
"type": "string"
}
},
{
"name": "not_in_team",
"in": "query",
"description": "The ID of the team to exclude users for. Must not be used with \"in_team\" query parameter.",
"schema": {
"type": "string"
}
},
{
"name": "in_channel",
"in": "query",
"description": "The ID of the channel to get users for.",
"schema": {
"type": "string"
}
},
{
"name": "not_in_channel",
"in": "query",
"description": "The ID of the channel to exclude users for. Must be used with \"in_channel\" query parameter.",
"schema": {
"type": "string"
}
},
{
"name": "in_group",
"in": "query",
"description": "The ID of the group to get users for. Must have `manage_system` permission.",
"schema": {
"type": "string"
}
},
{
"name": "group_constrained",
"in": "query",
"description": "When used with `not_in_channel` or `not_in_team`, returns only the users that are allowed to join the channel or team based on its group constrains.",
"schema": {
"type": "boolean"
}
},
{
"name": "without_team",
"in": "query",
"description": "Whether or not to list users that are not on any team. This option takes precendence over `in_team`, `in_channel`, and `not_in_channel`.",
"schema": {
"type": "boolean"
}
},
{
"name": "active",
"in": "query",
"description": "Whether or not to list only users that are active. This option cannot be used along with the `inactive` option.",
"schema": {
"type": "boolean"
}
},
{
"name": "inactive",
"in": "query",
"description": "Whether or not to list only users that are deactivated. This option cannot be used along with the `active` option.",
"schema": {
"type": "boolean"
}
},
{
"name": "role",
"in": "query",
"description": "Returns users that have this role.",
"schema": {
"type": "string"
}
},
{
"name": "sort",
"in": "query",
"description": "Sort is only available in conjunction with certain options below. The paging parameter is also always available.\n\n##### `in_team`\nCan be \"\", \"last_activity_at\" or \"create_at\".\nWhen left blank, sorting is done by username.\n__Minimum server version__: 4.0\n##### `in_channel`\nCan be \"\", \"status\".\nWhen left blank, sorting is done by username. `status` will sort by User's current status (Online, Away, DND, Offline), then by Username.\n__Minimum server version__: 4.7\n",
"schema": {
"type": "string"
}
},
{
"name": "roles",
"in": "query",
"description": "Comma separated string used to filter users based on any of the specified system roles\n\nExample: `?roles=system_admin,system_user` will return users that are either system admins or system users\n\n__Minimum server version__: 5.26\n",
"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`\n\nExample: `?in_channel=4eb6axxw7fg3je5iyasnfudc5y&channel_roles=channel_user` will return users that are only channel users and not admins or guests\n\n__Minimum server version__: 5.26\n",
"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`\n\nExample: `?in_team=4eb6axxw7fg3je5iyasnfudc5y&team_roles=team_user` will return users that are only team users and not admins or guests\n\n__Minimum server version__: 5.26\n",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "User page retrieval successful",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/User"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\n\n// page, perPage, etag\nusers := Client.GetUsers(0, 60, \"\")\nusers = Client.GetUsersInChannel(\"channelid\", 0, 60, \"\")\nusers = Client.GetUsersNotInChannel(\"teamid\", \"channelid\", 0, 60, \"\")\nusers = Client.GetUsersInTeam(\"teamid\", 0, 60, \"\")\nusers = Client.GetUsersNotInTeam(\"teamid\", 0, 60, \"\")\nusers = Client.GetUsersWithoutTeam(0, 60, \"\")\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n//get users\n$resp = $driver->getUserModel()->getUsers([\n \"page\" => 0,\n \"per_page\" => 60,\n]);\n\n//get users in channel\n$resp = $driver->getUserModel()->getUsers([\n \"in_channel\" => \"channelid\",\n \"page\" => 0,\n \"per_page\" => 60,\n]);\n\n//get users not in channel\n$resp = $driver->getUserModel()->getUsers([\n \"in_team\" => \"teamid\",\n \"not_in_channel\" => \"channelid\",\n \"page\" => 0,\n \"per_page\" => 60,\n]);\n\n//get users in team\n$resp = $driver->getUserModel()->getUsers([\n \"in_team\" => \"teamid\",\n \"page\" => 0,\n \"per_page\" => 60,\n]);\n\n//get users not in team\n$resp = $driver->getUserModel()->getUsers([\n \"not_in_team\" => \"teamid\",\n \"page\" => 0,\n \"per_page\" => 60,\n]);\n\n//get users without team\n$resp = $driver->getUserModel()->getUsers([\n \"without_team\" => true,\n \"page\" => 0,\n \"per_page\" => 60,\n]);\n\nif ($resp->getStatusCode() == 200) {\n $users = json_decode($resp->getBody());\n}\n"
}
]
},
"delete": {
"tags": [
"users"
],
"summary": "Permanent delete all users",
"description": "Permanently deletes all users and all their related information, including posts.\n\n__Minimum server version__: 5.26.0\n\n__Local mode only__: This endpoint is only available through [local mode](https://docs.mattermost.com/administration/mmctl-cli-tool.html#local-mode).\n",
"operationId": "PermanentDeleteAllUsers",
"responses": {
"200": {
"description": "Delete request was successful"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import (\n \"net\"\n \"net/http\"\n\n \"github.com/mattermost/mattermost-server/v5/model\"\n)\n\ntr := &http.Transport{\n Dial: func(network, addr string) (net.Conn, error) {\n return net.Dial(\"unix\", socketPath)\n },\n}\n\nClient := model.NewAPIv4Client(\"http://_\")\nClient.HttpClient = &http.Client{Transport: tr}\n\nok, resp := Client.PermanentDeleteAllUsers()\n"
}
]
}
},
"/users/ids": {
"post": {
"tags": [
"users"
],
"summary": "Get users by ids",
"description": "Get a list of users based on a provided list of user ids.\n##### Permissions\nRequires an active session but no other permissions.\n",
"operationId": "GetUsersByIds",
"parameters": [
{
"name": "since",
"in": "query",
"description": "Only return users that have been modified since the given Unix timestamp (in milliseconds).\n\n__Minimum server version__: 5.14\n",
"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"
}
}
}
},
"/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\nquery and its value as a list of users members of that group\nchannel.\n\nThe user must be a member of the group ids in the query, or\nthey will be omitted from the response.\n##### Permissions\nRequires an active session but no other permissions.\n\n__Minimum server version__: 5.14\n",
"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": {
"<CHANNEL_ID>": {
"type": "array",
"items": {
"$ref": "#/components/schemas/User"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/users/usernames": {
"post": {
"tags": [
"users"
],
"summary": "Get users by usernames",
"description": "Get a list of users based on a provided list of usernames.\n##### Permissions\nRequires an active session but no other permissions.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nusers, resp := Client.GetUsersByUsernames([]string{\"username1\", \"username2\"})\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$resp = $driver->getUserModel()->getUsersByUsernames([\n \"username1\",\n \"username2\",\n]);\n\nif ($resp->getStatusCode() == 200) {\n $users = json_decode($resp->getBody());\n}\n"
}
]
}
},
"/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.\n##### Permissions\nRequires an active session and `read_channel` and/or `view_team` permissions for any channels or teams specified in the request body.\n",
"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\n\n__Available as of server version 5.6. Defaults to `100` if not provided or on an earlier server version.__\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nteamID := \"4xp9fdt77pncbef59f4k1qe83o\"\nteamID2 := \"JhMjDX9rAlCdBf0l9oyq4eGhxw\"\nchannelID := \"Ej3SKOHlWIKAblkUTK5Xvkj2cm\"\nchannelID2 := \"dWdfrUSdjJ7kyBvyBCgCav67Kz\"\n\nusers, resp := Client.SearchUsers(&model.UserSearch{\n Term: \"searchTerm\",\n TeamId: teamID,\n NotInTeamId: teamID2,\n InChannelId: channelID,\n NotInChannelId: channelID2,\n AllowInactive: true,\n WithoutTeam: true,\n Limit: 100,\n Role: \"admin\",\n})\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$teamID = \"4xp9fdt77pncbef59f4k1qe83o\";\n$teamID2 = \"JhMjDX9rAlCdBf0l9oyq4eGhxw\";\n$channelID = \"Ej3SKOHlWIKAblkUTK5Xvkj2cm\";\n$channelID2 = \"dWdfrUSdjJ7kyBvyBCgCav67Kz\";\n\n$resp = $driver->getUserModel()->searchUsers([\n \"term\" => \"searchTerm\",\n \"team_id\" => $teamID,\n \"not_in_team_id\" => $teamID2,\n \"in_channel_id\" => $channelID,\n \"not_in_channel_id\" => $channelID2,\n \"allow_inactive\" => true,\n \"without_team\" => true,\n \"limit\" => 100,\n]);\n\nif ($resp->getStatusCode() == 200) {\n $users = json_decode($resp->getBody());\n}\n"
}
]
}
},
"/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.\n##### Permissions\nRequires an active session and `view_team` and `read_channel` on any teams or channels used to filter the results further.\n",
"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\n\n__Available as of server version 5.6. Defaults to `100` if not provided or on an earlier server version.__\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nteamID := \"4xp9fdt77pncbef59f4k1qe83o\"\nchannelID := \"Ej3SKOHlWIKAblkUTK5Xvkj2cm\"\nusername := \"testUsername\"\n\nusers, resp := Client.AutocompleteUsersInChannel(teamID, channelID, username, 100, \"\")\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$teamID = \"4xp9fdt77pncbef59f4k1qe83o\";\n$channelID = \"Ej3SKOHlWIKAblkUTK5Xvkj2cm\";\n$username = \"testUsername\";\n\n$resp = $driver->getUserModel()->autocompleteUsers([\n \"team_id\" => $teamID,\n \"channel_id\" => $channelID,\n \"name\" => $username,\n \"limit\" => 100,\n]);\n\nif ($resp->getStatusCode() == 200) {\n $users = json_decode($resp->getBody());\n}\n"
}
]
}
},
"/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\nuser. That means any user sharing any channel, including direct and\ngroup channels.\n##### Permissions\nMust be authenticated.\n\n__Minimum server version__: 5.23\n",
"operationId": "GetKnownUsers",
"responses": {
"200": {
"description": "Known users' IDs retrieval successful",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UsersStats"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nuserIds, resp := Client.GetKnownUsers()\n"
}
]
}
},
"/users/stats": {
"get": {
"tags": [
"users"
],
"summary": "Get total count of users in the system",
"description": "Get a total count of users in the system.\n##### Permissions\nMust be authenticated.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nstats, resp := Client.GetTotalUsersStats(\"\")\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$resp = $driver->getUserModel()->getTotalCountOfUsersInTheSystem();\n\nif ($resp->getStatusCode() == 200) {\n $stats = json_decode($resp->getBody())->total_users_count;\n}\n"
}
]
}
},
"/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.\n\n__Minimum server version__: 5.26\n\n##### Permissions\nMust have `manage_system` permission.\n",
"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\n\nExample: `?roles=system_admin,system_user` will include users that are either system admins or system users\n",
"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`\n\nExample: `?in_channel=4eb6axxw7fg3je5iyasnfudc5y&channel_roles=channel_user` will include users that are only channel users and not admins or guests\n",
"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`\n\nExample: `?in_team=4eb6axxw7fg3je5iyasnfudc5y&team_roles=team_user` will include users that are only team users and not admins or guests\n",
"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"
}
}
}
},
"/users/{user_id}": {
"get": {
"tags": [
"users"
],
"summary": "Get a user",
"description": "Get a user a object. Sensitive information will be sanitized out.\n##### Permissions\nRequires an active session but no other permissions.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nuserID := \"4xp9fdt77pncbef59f4k1qe83o\"\n\nuser, resp := Client.GetUser(userID, \"\")\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$userID = \"4xp9fdt77pncbef59f4k1qe83o\";\n\n$resp = $driver->getUserModel()->getUser($userID);\n\nif ($resp->getStatusCode() == 200) {\n $user = json_decode($resp->getBody());\n}\n"
}
]
},
"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.\n##### Permissions\nMust be logged in as the user being updated or have the `edit_other_users` permission.\n",
"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"
],
"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"
},
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nuserID := \"4xp9fdt77pncbef59f4k1qe83o\"\nemail := \"test@domain.com\"\nusername := \"testUsername\"\nfirstName := \"testFirstname\"\nlastName := \"testLastname\"\nnickname := \"testNickname\"\nlocale := \"en\"\nposition := \"testPosition\"\nprops := model.StringMap{}\nprops[\"testPropKey\"] = \"testPropValue\"\nnotifyProps := model.StringMap{}\nnotifyProps[\"comment\"] = \"somethingrandom\"\n\nuser, resp := Client.UpdateUser(&model.User{\n Id: userID,\n Email: email,\n Username: username,\n FirstName: firstName,\n LastName: lastName,\n Nickname: nickname,\n Locale: locale,\n Position: position,\n Props: props,\n NotifyProps: notifyProps,\n})\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$userID = \"4xp9fdt77pncbef59f4k1qe83o\";\n$email = \"test@domain.com\";\n$username = \"testUsername\";\n$firstName = \"testFirstname\";\n$lastName = \"testLastname\";\n$nickname = \"testNickname\";\n$locale = \"en\";\n$position = \"testPosition\";\n$props = [];\n$props[\"testPropKey\"] = \"testPropValue\";\n$notifyProps = [];\n$notifyProps[\"comment\"] = \"somethingrandom\";\n\n$resp = $driver->getUserModel()->updateUser($userID, [\n \"email\" => $email,\n \"username\" => $username,\n \"first_name\" => $firstName,\n \"last_name\" => $lastName,\n \"nickname\" => $nickname,\n \"locale\" => $locale,\n \"position\" => $position,\n \"props\" => $props,\n \"notify_props\" => $notifyProps,\n]);\n\nif ($resp->getStatusCode() == 200) {\n $user = json_decode($resp->getBody());\n}\n"
}
]
},
"delete": {
"tags": [
"users"
],
"summary": "Deactivate a user account.",
"description": "Deactivates the user and revokes all its sessions by archiving its user object.\n\nAs 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.\n##### Permissions\nMust be logged in as the user being deactivated or have the `edit_other_users` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nuserID := \"4xp9fdt77pncbef59f4k1qe83o\"\n\nok, resp := Client.DeleteUser(userID)\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$userID = \"4xp9fdt77pncbef59f4k1qe83o\";\n\n$resp = $driver->getUserModel()->deactivateUserAccount($userID);\n\nif ($resp->getStatusCode() == 200) {\n $ok = json_decode($resp->getBody())->status;\n}\n"
}
]
}
},
"/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.\n##### Permissions\nMust be logged in as the user being updated or have the `edit_other_users` permission.\n",
"operationId": "PatchUser",
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "User GUID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"email": {
"type": "string"
},
"username": {
"type": "string"
},
"first_name": {
"type": "string"
},
"last_name": {
"type": "string"
},
"nickname": {
"type": "string"
},
"locale": {
"type": "string"
},
"position": {
"type": "string"
},
"props": {
"type": "object"
},
"notify_props": {
"$ref": "#/components/schemas/UserNotifyProps"
}
}
}
}
},
"description": "User object that is to be updated",
"required": true
},
"responses": {
"200": {
"description": "User patch successful",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/User"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nuserID := \"4xp9fdt77pncbef59f4k1qe83o\"\n\npatch := &model.UserPatch{}\npatch.Email = model.NewString(\"test@domain.com\")\npatch.Username = model.NewString(\"testUsername\")\npatch.FirstName = model.NewString(\"testFirstname\")\npatch.LastName = model.NewString(\"testLastname\")\npatch.Nickname = model.NewString(\"testNickname\")\npatch.Locale = model.NewString(\"en\")\npatch.Position = model.NewString(\"testPosition\")\npatch.Props = model.StringMap{}\npatch.Props[\"testPropKey\"] = \"testPropValue\"\npatch.NotifyProps = model.StringMap{}\npatch.NotifyProps[\"comment\"] = \"somethingrandom\"\n\nuser, resp := Client.PatchUser(userID, patch)\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$userID = \"4xp9fdt77pncbef59f4k1qe83o\";\n$email = \"test@domain.com\";\n$username = \"testUsername\";\n$firstName = \"testFirstname\";\n$lastName = \"testLastname\";\n$nickname = \"testNickname\";\n$locale = \"en\";\n$position = \"testPosition\";\n$props = [];\n$props[\"testPropKey\"] = \"testPropValue\";\n$notifyProps = [];\n$notifyProps[\"comment\"] = \"somethingrandom\";\n\n$resp = $driver->getUserModel()->patchUser($userID, [\n \"email\" => $email,\n \"username\" => $username,\n \"first_name\" => $firstName,\n \"last_name\" => $lastName,\n \"nickname\" => $nickname,\n \"locale\" => $locale,\n \"position\" => $position,\n \"props\" => $props,\n \"notify_props\" => $notifyProps,\n]);\n\nif ($resp->getStatusCode() == 200) {\n $user = json_decode($resp->getBody());\n}\n"
}
]
}
},
"/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.\n##### Permissions\nMust have the `manage_roles` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nuserID := \"4xp9fdt77pncbef59f4k1qe83o\"\nroles := \"team_user team_admin\"\n\nok, resp = Client.UpdateUserRoles(userID, roles)\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$userID = \"4xp9fdt77pncbef59f4k1qe83o\";\n$roles = \"team_user team_admin\";\n\n$resp = $driver->getUserModel()->updateUserRoles($userID, [\n \"roles\" => $roles,\n]);\n\nif ($resp->getStatusCode() == 200) {\n $ok = json_decode($resp->getBody())->status;\n}\n"
}
]
}
},
"/users/{user_id}/active": {
"put": {
"tags": [
"users"
],
"summary": "Update user active status",
"description": "Update user active or inactive status.\n\n__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.__\n##### Permissions\nUser can deactivate themselves.\nUser with `manage_system` permission can activate or deactivate a user.\n",
"operationId": "UpdateUserActive",
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "User GUID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"active"
],
"properties": {
"active": {
"type": "boolean"
}
}
}
}
},
"description": "Use `true` to set the user active, `false` for inactive",
"required": true
},
"responses": {
"200": {
"description": "User active status update successful",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StatusOK"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nuserID := \"4xp9fdt77pncbef59f4k1qe83o\"\n\nok, resp := Client.UpdateUserActive(userID, true)\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$userID = \"4xp9fdt77pncbef59f4k1qe83o\";\n\n$resp = $driver->getUserModel()->updateUserActive($userID, [\n \"active\" => true,\n]);\n\nif ($resp->getStatusCode() == 200) {\n $ok = json_decode($resp->getBody())->status;\n}\n"
}
]
}
},
"/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.\n##### Permissions\nMust be logged in.\n",
"operationId": "GetProfileImage",
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "User GUID",
"required": true,
"schema": {
"type": "string"
}
}
],
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nuserID := \"4xp9fdt77pncbef59f4k1qe83o\"\n\ndata, resp := Client.GetProfileImage(userID, \"\")\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$userID = \"4xp9fdt77pncbef59f4k1qe83o\";\n\n$resp = $driver->getUserModel()->getUserProfileImage($userID);\n\nif ($resp->getStatusCode() == 200) {\n $data = json_decode($resp->getBody());\n}\n"
}
]
},
"post": {
"tags": [
"users"
],
"summary": "Set user's profile image",
"description": "Set a user's profile image based on user_id string parameter.\n##### Permissions\nMust be logged in as the user being updated or have the `edit_other_users` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import (\n \"io/ioutil\"\n \"log\"\n\n \"github.com/mattermost/mattermost-server/v5/model\"\n)\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\ndata, err := ioutil.ReadFile(\"profile_pic.png\")\nif err != nil {\n log.Fatal(err)\n}\n\nuserID := \"4xp9fdt77pncbef59f4k1qe83o\"\n\nok, resp := Client.SetProfileImage(userID, data)\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$userID = \"4xp9fdt77pncbef59f4k1qe83o\";\n$resource = fopen(\"profile_pic.png\", 'rb');\n\nif ($resource === false) {\n throw new \\Exeption(\"Failure.\");\n}\n\n$data = new \\GuzzleHttp\\Psr7\\Stream($resource);\n\n$resp = $driver->getUserModel()->setUserProfileImage($userID, [\n \"image\" => $data,\n]);\n\nfclose($resource);\n\nif ($resp->getStatusCode() == 200) {\n $ok = json_decode($resp->getBody()->status;\n}\n"
}
]
},
"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.\n##### Permissions\nMust be logged in as the user being updated or have the `edit_other_users` permission.\n__Minimum server version__: 5.5\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nuserID := \"4xp9fdt77pncbef59f4k1qe83o\"\n\n// Deleting user's profile image consists on resetting it to default one\nok, resp := Client.SetDefaultProfileImage(userID)\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$userID = \"4xp9fdt77pncbef59f4k1qe83o\";\n\n$resp = $driver->getUserModel()->deleteUserProfileImage($userID);\n\nif ($resp->getStatusCode() == 200) {\n $ok = json_decode($resp->getBody()->status;\n}\n"
}
]
}
},
"/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.\n##### Permissions\nMust be logged in.\n__Minimum server version__: 5.5\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nuserID := \"4xp9fdt77pncbef59f4k1qe83o\"\n\nok, resp := Client.SetDefaultProfileImage(userID)\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$userID = \"4xp9fdt77pncbef59f4k1qe83o\";\n\n$resp = $driver->getUserModel()->returnUserDefaultProfileImage($userID);\n\nif ($resp->getStatusCode() == 200) {\n $ok = json_decode($resp->getBody();\n}\n"
}
]
}
},
"/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.\n##### Permissions\nRequires an active session but no other permissions.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nuserID := \"4xp9fdt77pncbef59f4k1qe83o\"\n\nuser, resp := Client.GetUserByUsername(userID, \"\")\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$username = \"username\";\n\n$resp = $driver->getUserModel()->getUserByUsername($username);\n\nif ($resp->getStatusCode() == 200) {\n $user = json_decode($resp->getBody());\n}\n"
}
]
}
},
"/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.\n##### Permissions\nNo permissions required.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\ncode := \"4xp9fdt77pncbef59f4k1qe83o\"\nnewPassword := \"awesomePassword\"\n\nsuccess, resp = Client.ResetPassword(code, newPassword)\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$code = \"4xp9fdt77pncbef59f4k1qe83o\";\n$newPassword = \"awesomePassword\";\n\n$resp = $driver->getUserModel()->resetPassword([\n \"code\" => $code,\n \"newPassword\" => $newPassword,\n]);\n\nif ($resp->getStatusCode() == 200) {\n $success = json_decode($resp->getBody())->status;\n}\n"
}
]
}
},
"/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.\n##### Permissions\nMust be logged in as the user being updated or have the `edit_other_users` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nuserID := \"BbaYBYDV5IDOZFiJGBSzkw1k5u\"\ncode := \"4xp9fdt77pncbef59f4k1qe83o\"\n\nok, resp := Client.UpdateUserMfa(userID, code, true)\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$userID = \"BbaYBYDV5IDOZFiJGBSzkw1k5u\";\n$code = \"4xp9fdt77pncbef59f4k1qe83o\";\n\n$resp = $driver->getUserModel()->updateUserMfa($userID, [\n \"activate\" => true,\n \"code\" => $code,\n]);\n\nif ($resp->getStatusCode() == 200) {\n $ok = json_decode($resp->getBody()->status;\n}\n"
}
]
}
},
"/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.\n##### Permissions\nMust be logged in as the user or have the `edit_other_users` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nuserID := \"BbaYBYDV5IDOZFiJGBSzkw1k5u\"\n\nmfaSecret, resp = Client.GenerateMfaSecret(userID)\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$userID = \"BbaYBYDV5IDOZFiJGBSzkw1k5u\";\n\n$resp = $driver->getUserModel()->generateMfaSecret($userID);\n\nif ($resp->getStatusCode() == 200) {\n $mfaSecret = json_decode($resp->getBody());\n}\n"
}
]
}
},
"/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\nguest for the whole system while retaining their existing team and\nchannel memberships.\n\n__Minimum server version__: 5.16\n\n##### Permissions\nMust be logged in as the user or have the `demote_to_guest` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nuserID := \"BbaYBYDV5IDOZFiJGBSzkw1k5u\"\n\nok, resp = Client.demoteUserToGuest(userID)\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$userID = \"BbaYBYDV5IDOZFiJGBSzkw1k5u\";\n\n$resp = $driver->getUserModel()->demoteUserToGuest($userID);\n\nif ($resp->getStatusCode() == 200) {\n $ok = json_decode($resp->getBody()->status;\n}\n"
}
]
}
},
"/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\nuser for the whole system while retaining any team and channel\nmemberships and automatically joining them to the default channels.\n\n__Minimum server version__: 5.16\n\n##### Permissions\nMust be logged in as the user or have the `promote_guest` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nuserID := \"BbaYBYDV5IDOZFiJGBSzkw1k5u\"\n\nok, resp = Client.PromoteGuestToUser(userID)\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$userID = \"BbaYBYDV5IDOZFiJGBSzkw1k5u\";\n\n$resp = $driver->getUserModel()->promoteGuestToUser($userID);\n\nif ($resp->getStatusCode() == 200) {\n $ok = json_decode($resp->getBody()->status;\n}\n"
}
]
}
},
"/users/{user_id}/convert_to_bot": {
"post": {
"tags": [
"bots",
"users"
],
"summary": "Convert a user into a bot",
"description": "Convert a user into a bot.\n\n__Minimum server version__: 5.26\n\n##### Permissions\nMust have `manage_system` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\n\nuserId := \"BbaYBYDV5IDOZFiJGBSzkw1k5u\"\n\nbot, resp := Client.ConvertUserToBot(userId)\n"
}
]
}
},
"/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.\n##### Permissions\nNo permission required.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\n\nloginID := \"test@domain.com\"\n\nrequired, resp := Client.CheckUserMfa(loginID)\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$loginID = \"test@domain.com\";\n\n$resp = $driver->getUserModel()->checkMfa([\n \"login_id\" => $loginID,\n]);\n\nif ($resp->getStatusCode() == 200) {\n $required = json_decode($resp->getBody())->mfa_required;\n}\n"
}
]
}
},
"/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.\n##### Permissions\nMust be logged in as the user the password is being changed for or have `manage_system` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nuserID := \"BbaYBYDV5IDOZFiJGBSzkw1k5u\"\ncurrentPassword := \"badPassword\"\nnewPassword := \"awesomePassword\"\n\nok, resp := Client.UpdateUserPassword(userID, currentPassword, newPassword)\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$userID = \"BbaYBYDV5IDOZFiJGBSzkw1k5u\";\n$currentPassword = \"badPassword\";\n$newPassword = \"awesomePassword\";\n\n$resp = $driver->getUserModel()->updateUserPassword($userID, [\n \"current_password\" => $currentPassword,\n \"new_password\" => $newPassword,\n]);\n\nif ($resp->getStatusCode() == 200) {\n $ok = json_decode($resp->getBody())->status;\n}\n"
}
]
}
},
"/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.\n##### Permissions\nNo permissions required.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\n\nemail := \"test@domain.com\"\n\npass, resp := Client.SendVerificationEmail(email)\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$email = \"test@domain.com\";\n\n$resp = $driver->getUserModel()->sendPasswordResetEmail([\n \"email\" => $email,\n]);\n\nif ($resp->getStatusCode() == 200) {\n $pass = json_decode($resp->getBody())->status;\n}\n"
}
]
}
},
"/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.\n##### Permissions\nRequires an active session and for the current session to be able to view another user's email based on the server's privacy settings.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nemail := \"test@domain.com\"\n\nuser, resp := Client.GetUserByEmail(email, \"\")\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$email = \"test@domain.com\";\n\n$resp = $driver->getUserModel()->getUserByEmail($email);\n\nif ($resp->getStatusCode() == 200) {\n $user = json_decode($resp->getBody());\n}\n"
}
]
}
},
"/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.\n##### Permissions\nMust be logged in as the user being updated or have the `edit_other_users` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nuserID := \"zWEyrTZ7GZ22aBSfoX60iWryTY\"\n\nsessions, resp := Client.GetSessions(userID, \"\")\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$userID = \"zWEyrTZ7GZ22aBSfoX60iWryTY\";\n\n$resp = $driver->getUserModel()->getUserSessions($userID);\n\nif ($resp->getStatusCode() == 200) {\n $sessions = json_decode($resp->getBody());\n}\n"
}
]
}
},
"/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.\n##### Permissions\nMust be logged in as the user being updated or have the `edit_other_users` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nuserID := \"zWEyrTZ7GZ22aBSfoX60iWryTY\"\nsessionID := \"adWv1qPZmHdtxk7Lmqh6RtxWxS\"\n\nok, resp = Client.RevokeSession(userID, sessionID)\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$userID = \"zWEyrTZ7GZ22aBSfoX60iWryTY\";\n$sessionID = \"adWv1qPZmHdtxk7Lmqh6RtxWxS\";\n\n$resp = $driver->getUserModel()->revokeUserSession($userID, [\n \"session_id\" => $sessionID,\n]);\n\nif ($resp->getStatusCode() == 200) {\n $ok = json_decode($resp->getBody())->status;\n}\n"
}
]
}
},
"/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.\n##### Permissions\nMust be logged in as the user being updated or have the `edit_other_users` permission.\n__Minimum server version__: 4.4\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nuserID := \"zWEyrTZ7GZ22aBSfoX60iWryTY\"\n\nok, resp := Client.RevokeAllSessions(userID)\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$userID = \"zWEyrTZ7GZ22aBSfoX60iWryTY\";\n\n$resp = $driver->getUserModel()->revokeAllUserSessions($userID);\n\nif ($resp->getStatusCode() == 200) {\n $ok = json_decode($resp->getBody())->status;\n}\n"
}
]
}
},
"/users/sessions/device": {
"put": {
"tags": [
"users"
],
"summary": "Attach mobile device",
"description": "Attach a mobile device id to the currently logged in session. This will enable push notifications for a user, if configured by the server.\n##### Permissions\nMust be authenticated.\n",
"operationId": "AttachDeviceId",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"device_id"
],
"properties": {
"device_id": {
"description": "Mobile device id. For Android prefix the id with `android:` and Apple with `apple:`",
"type": "string"
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Device id attach successful",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StatusOK"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\ndeviceID := \"zWEyrTZ7GZ22aBSfoX60iWryTY\"\n\npass, resp := Client.AttachDeviceId(deviceID)\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$deviceID = \"zWEyrTZ7GZ22aBSfoX60iWryTY\";\n\n$resp = $driver->getUserModel()->attachMobileDevice([\n \"device_id\" => $deviceID,\n]);\n\nif ($resp->getStatusCode() == 200) {\n $pass = json_decode($resp->getBody())->status;\n}\n"
}
]
}
},
"/users/{user_id}/audits": {
"get": {
"tags": [
"users"
],
"summary": "Get user's audits",
"description": "Get a list of audit by providing the user GUID.\n##### Permissions\nMust be logged in as the user or have the `edit_other_users` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nuserID := \"zWEyrTZ7GZ22aBSfoX60iWryTY\"\n\naudits, resp := Client.GetUserAudits(userID, 0, 100, \"\")\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$userID = \"zWEyrTZ7GZ22aBSfoX60iWryTY\";\n\n$resp = $driver->getUserModel()->getUserAudits($userID);\n\nif ($resp->getStatusCode() == 200) {\n $audits = json_decode($resp->getBody());\n}\n"
}
]
}
},
"/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.\n\n__Minimum server version__: 5.24\n\n##### Permissions\n\nMust have `manage_system` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nuserID := \"BbaYBYDV5IDOZFiJGBSzkw1k5u\n\nuser, resp := Client.VerifyUserEmailWithoutToken(userID)\n"
}
]
}
},
"/users/email/verify": {
"post": {
"tags": [
"users"
],
"summary": "Verify user email",
"description": "Verify the email used by a user to sign-up their account with.\n##### Permissions\nNo permissions required.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\n\ntoken := \"zWEyrTZ7GZ22aBSfoX60iWryTY\"\n\nok, resp := Client.VerifyUserEmail(token)\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$token = \"zWEyrTZ7GZ22aBSfoX60iWryTY\";\n\n$resp = $driver->getUserModel()->verifyUserEmail([\n \"token\" => $token,\n]);\n\nif ($resp->getStatusCode() == 200) {\n $ok = json_decode($resp->getBody())->status;\n}\n"
}
]
}
},
"/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.\n##### Permissions\nNo permissions required.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\n\nemail := \"test@domain.com\"\n\npass, resp := Client.SendVerificationEmail(email)\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$email = \"test@domain.com\";\n\n$resp = $driver->getUserModel()->sendVerificationEmail([\n \"email\" => $email,\n]);\n\nif ($resp->getStatusCode() == 200) {\n $pass = json_decode($resp->getBody())->status;\n}\n"
}
]
}
},
"/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.\n\nTo switch from email to OAuth2/SAML, specify `current_service`, `new_service`, `email` and `password`.\n\nTo switch from OAuth2/SAML to email, specify `current_service`, `new_service`, `email` and `new_password`.\n\nTo 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).\n\nTo 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`.\n\nAdditionally, specify `mfa_code` when trying to switch an account on LDAP/AD or email that has MFA activated.\n\n##### Permissions\nNo current authentication required except when switching from OAuth2/SAML to email.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\n\ncurrentService := \"email\"\nnewService := \"gitlab\"\nemail := \"test@domain.com\"\npassword := \"awesomePassword\"\nmfaCode := \"adWv1qPZmHdtxk7Lmqh6RtxWxS\"\nldapLoginID := \"RdDjEDlkWgt7ndjyVLwWGvnX8c\"\n\n\nlink, resp := Client.SwitchAccountType(&model.SwitchRequest{\n CurrentService: currentService,\n NewService: newService,\n Email: email,\n Password: password,\n MfaCode: mfaCode,\n LdapLoginId: ldapLoginID,\n})\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$currentService = \"email\";\n$newService = \"gitlab\";\n$email = \"test@domain.com\";\n$password = \"awesomePassword\";\n$mfaCode = \"adWv1qPZmHdtxk7Lmqh6RtxWxS\";\n$ldapLoginID = \"RdDjEDlkWgt7ndjyVLwWGvnX8c\";\n\n$resp = $driver->getUserModel()->switchLoginMethod([\n \"current_service\" => $currentService,\n \"new_service\" => $newService,\n \"email\" => $email,\n \"password\" => $password,\n \"mfa_code\" => $mfaCode,\n \"ldap_id\" => $ldapLoginID,\n]);\n\nif ($resp->getStatusCode() == 200) {\n $link = json_decode($resp->getBody())->follow_link;\n}\n"
}
]
}
},
"/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.\n\n__Minimum server version__: 4.1\n\n##### Permissions\nMust have `create_user_access_token` permission. For non-self requests, must also have the `edit_other_users` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nuserID := \"adWv1qPZmHdtxk7Lmqh6RtxWxS\"\n\nuserAccessToken, resp := Client.CreateUserAccessToken(userID, \"test token\")\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$userID = \"adWv1qPZmHdtxk7Lmqh6RtxWxS\";\n\n$resp = $driver->getUserModel()->createToken($userID, [\n \"description\" => \"test token\",\n]);\n\nif ($resp->getStatusCode() == 200) {\n $userAccessToken = json_decode($resp->getBody());\n}\n"
}
]
},
"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.\n\n__Minimum server version__: 4.1\n\n##### Permissions\nMust have `read_user_access_token` permission. For non-self requests, must also have the `edit_other_users` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nuserID := \"adWv1qPZmHdtxk7Lmqh6RtxWxS\"\n\ntokens, resp := Client.GetUserAccessTokensForUser(userID, 0, 100)\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$userID = \"adWv1qPZmHdtxk7Lmqh6RtxWxS\";\n\n$resp = $driver->getUserModel()->getTokens($userID, [\n \"page\" => 0,\n \"per_page\" => 100,\n]);\n\nif ($resp->getStatusCode() == 200) {\n $tokens = json_decode($resp->getBody());\n}\n"
}
]
}
},
"/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.\n\n__Minimum server version__: 4.7\n\n##### Permissions\nMust have `manage_system` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\ntokens, resp := Client.GetUserAccessTokens(0, 100)\n"
}
]
}
},
"/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.\n\n__Minimum server version__: 4.1\n\n##### Permissions\nMust have `revoke_user_access_token` permission. For non-self requests, must also have the `edit_other_users` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\ntokenID := \"adWv1qPZmHdtxk7Lmqh6RtxWxS\"\n\nok, resp := Client.RevokeUserAccessToken(tokenID)\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$tokenID = \"adWv1qPZmHdtxk7Lmqh6RtxWxS\";\n\n$resp = $driver->getUserModel()->revokeToken([\n \"token_id\" => $tokenID,\n]);\n\nif ($resp->getStatusCode() == 200) {\n $ok = json_decode($resp->getBody())->status;\n}\n"
}
]
}
},
"/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.\n\n__Minimum server version__: 4.1\n\n##### Permissions\nMust have `read_user_access_token` permission. For non-self requests, must also have the `edit_other_users` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\ntokenID := \"adWv1qPZmHdtxk7Lmqh6RtxWxS\"\n\ntoken, resp := Client.GetUserAccessToken(tokenID)\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$tokenID = \"adWv1qPZmHdtxk7Lmqh6RtxWxS\";\n\n$resp = $driver->getUserModel()->getToken($tokenID);\n\nif ($resp->getStatusCode() == 200) {\n $token = json_decode($resp->getBody());\n}\n"
}
]
}
},
"/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`.\n\n__Minimum server version__: 4.4\n\n##### Permissions\nMust have `revoke_user_access_token` permission. For non-self requests, must also have the `edit_other_users` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\ntokenID := \"adWv1qPZmHdtxk7Lmqh6RtxWxS\"\n\nok, resp := Client.DisableUserAccessToken(tokenID)\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$tokenID = \"adWv1qPZmHdtxk7Lmqh6RtxWxS\";\n\n$resp = $driver->getUserModel()->disablePersonalAccessToken([\n \"token_id\" => $tokenID\n]);\n\nif ($resp->getStatusCode() == 200) {\n $ok = json_decode($resp->getBody())->status;\n}\n"
}
]
}
},
"/users/tokens/enable": {
"post": {
"tags": [
"users"
],
"summary": "Enable personal access token",
"description": "Re-enable a personal access token that has been disabled.\n\n__Minimum server version__: 4.4\n\n##### Permissions\nMust have `create_user_access_token` permission. For non-self requests, must also have the `edit_other_users` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\ntokenID := \"adWv1qPZmHdtxk7Lmqh6RtxWxS\"\n\nok, resp := Client.EnableUserAccessToken(tokenID)\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$tokenID = \"adWv1qPZmHdtxk7Lmqh6RtxWxS\";\n\n$resp = $driver->getUserModel()->enablePersonalAccessToken([\n \"token_id\" => $tokenID\n]);\n\nif ($resp->getStatusCode() == 200) {\n $ok = json_decode($resp->getBody())->status;\n}\n"
}
]
}
},
"/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.\n\n__Minimum server version__: 4.7\n\n##### Permissions\nMust have `manage_system` permission.\n",
"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"
}
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\ntokenID := \"adWv1qPZmHdtxk7Lmqh6RtxWxS\"\n\nuserAccessTokens, resp = Client.SearchUserAccessTokens(&model.UserAccessTokenSearch{Term: tokenID})\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$tokenID = \"adWv1qPZmHdtxk7Lmqh6RtxWxS\";\n\n$resp = $driver->getUserModel()->searchTokens([\n \"term\" => $tokenID\n]);\n\nif ($resp->getStatusCode() == 200) {\n $userAccessTokens = json_decode($resp->getBody());\n}\n"
}
]
}
},
"/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.\n\n__Minimum server version__: 4.6\n##### Permissions\nMust have the `edit_other_users` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nuserID := \"adWv1qPZmHdtxk7Lmqh6RtxWxS\"\nuser, resp := Client.GetUser(userID, \"\")\nuserAuth := &model.UserAuth{}\nuserAuth.AuthData = user.AuthData\nuserAuth.AuthService = user.AuthService\n\nuser, resp := Client.UpdateUserAuth(userID, userAuth)\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$userID = \"adWv1qPZmHdtxk7Lmqh6RtxWxS\";\n$resp = $driver->getUserModel()->getUser($userID);\n\nif ($resp->getStatusCode() == 200) {\n $user = json_decode($resp->getBody());\n} else {\n throw new \\Exception(\"User not found.\");\n}\n\n$userAuth = [];\n$userAuth[\"auth_data\"] = $user->auth_data;\n$userAuth[\"auth_service\"] = $user->auth_service;\n\n$resp = $driver->getUserModel()->updateUserAuthenticationMethod($userID, $userAuth);\n\nif ($resp->getStatusCode() == 200) {\n $user = json_decode($resp->getBody());\n}\n"
}
]
}
},
"/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.\nUpdates user's last accepted terms of service ID if they accepted it.\n\n__Minimum server version__: 5.4\n##### Permissions\nMust be logged in as the user being acted on.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nuserID := \"adWv1qPZmHdtxk7Lmqh6RtxWxS\"\nserviceTermsID := \"RdDjEDlkWgt7ndjyVLwWGvnX8c\"\n\nsuccess, resp = Client.RegisterTermsOfServiceAction(userID, serviceTermsID, true)\n"
}
]
},
"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\nFetches user's latest terms of service action if the latest action was for acceptance.\n\n__Minimum server version__: 5.6\n##### Permissions\nMust be logged in as the user being acted on.\n",
"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"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nuserID := \"adWv1qPZmHdtxk7Lmqh6RtxWxS\"\n\nuserTermsOfService, resp := Client.GetUserTermsOfService(userID, \"\")\n"
}
]
}
},
"/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.\nClients will be notified to log out users.\n\n__Minimum server version__: 5.14\n\n##### Permissions\nMust have `manage_system` permission.\n",
"operationId": "RevokeSessionsFromAllUsers",
"responses": {
"200": {
"description": "Sessions successfully revoked."
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nresponse, err := Client.RevokeSessionsFromAllUsers()\n"
}
]
}
},
"/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.\n__Minimum server version__: 5.26\n##### Permissions\nMust have `manage_system` permission to publish for any user other than oneself.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nok, response := Client.PublishUserTyping(userID, TypingRequest{\n ChannelId: \"channel_id\",\n ParentId: \"post_id\",\n})\n"
}
]
}
},
"/users/{user_id}/uploads": {
"get": {
"tags": [
"users"
],
"summary": "Get uploads for a user",
"description": "Gets all the upload sessions belonging to a user.\n\n__Minimum server version__: 5.28\n\n##### Permissions\nMust be logged in as the user who created the upload sessions.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\nuss, response := Client.GetUploadsForUser(\"fc6suoon9pbbpmhrb9c967paxe\")\n"
},
{
"lang": "Curl",
"source": "curl 'http://localhost:8065/api/v4/users/fc6suoon9pbbpmhrb9c967paxe/uploads' \\\n-H 'Authorization: Bearer 9kg8nqrnxprd9jbykqeg4r51hw' \\\n"
}
]
}
},
"/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.\n\n__Minimum server version__: 6.2.0\n\n##### Permissions\nLogged in as the user, or have `edit_other_users` permission.\n",
"operationId": "GetChannelMembersWithTeamDataForUser",
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "The ID of the user. This can also be \"me\" which will point to the current user.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "page",
"in": "query",
"description": "Page specifies which part of the results to return, by PageSize.",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "pageSize",
"in": "query",
"description": "PageSize specifies the size of the returned chunk of results.",
"required": false,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "User's uploads retrieval successful",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ChannelMemberWithTeamData"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\nchannels, response, err := Client.GetChannelMembersWithTeamData(\"fc6suoon9pbbpmhrb9c967paxe\", 0, 10)\n"
},
{
"lang": "Curl",
"source": "curl 'http://localhost:8065/api/v4/users/me/channel_members?page=0&per_page=2' \\\n-H 'Authorization: Bearer 9kg8nqrnxprd9jbykqeg4r51hw' \\\n"
}
]
}
},
"/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.\n__Minimum server version__: 5.28\n##### Permissions\nMust have `manage_system` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"sysadmin@domain.com\", \"Password1\")\n\nok, response := Client.MigrateAuthToLdap(fromAuthService, matchField, force)\n"
}
]
}
},
"/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.\n__Minimum server version__: 5.28\n##### Permissions\nMust have `manage_system` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"sysadmin@domain.com\", \"Password1\")\n\nok, response := Client.MigrateAuthToSaml(fromAuthService, usersMap, auto)\n"
}
]
}
},
"/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\n\n__Minimum server version__: 5.29\n\n##### Permissions\nMust be logged in as the user or have `edit_other_users` permission.\n",
"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 PageSize.",
"required": false,
"schema": {
"type": "integer",
"default": 0
}
},
{
"name": "pageSize",
"in": "query",
"description": "PageSize specifies the size of the returned chunk of results.",
"required": false,
"schema": {
"default": 30,
"type": "integer"
}
},
{
"name": "totalsOnly",
"in": "query",
"description": "Setting this to true will only return the total counts.",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\") Client.Login(\"email@domain.com\", \"Password1\")\nuss, response := Client.GetUserThreads(\"fc6suoon9pbbpmhrb9c967paxe\", \"fc6su111111pmhrb9c967paxe\", model.GetUserThreadsOpts{\n Deleted: true,\n Since: 123123,\n Page: 0,\n PageSize: 40,\n })\n"
},
{
"lang": "Curl",
"source": "curl 'http://localhost:8065/api/v4/users/fc6suoon9pbbpmhrb9c967paxe/threads' \\\n-H 'Authorization: Bearer 9kg8nqrnxprd9jbykqeg4r51hw' \\\n"
}
]
}
},
"/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\n\n__Minimum server version__: 5.29\n\n##### Permissions\nMust be logged in as the user or have `edit_other_users` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\nuss, response := Client.GetThreadMentionsForUserPerChannel(\"fc6suoon9pbbpmhrb9c967paxe\", \"fc6su111111pmhrb9c967paxe\")\n"
},
{
"lang": "Curl",
"source": "curl -X PUT 'http://localhost:8065/api/v4/users/fc6suoon9pbbpmhrb9c967paxe/threads/mention_counts' \\\n-H 'Authorization: Bearer 9kg8nqrnxprd9jbykqeg4r51hw' \\ \n"
}
]
}
},
"/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\n\n__Minimum server version__: 5.29\n\n##### Permissions\nMust be logged in as the user or have `edit_other_users` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\nuss, response := Client.UpdateThreadsReadForUser(\"fc6suoon9pbbpmhrb9c967paxe\", \"fc6su111111pmhrb9c967paxe\")\n"
},
{
"lang": "Curl",
"source": "curl -X PUT 'http://localhost:8065/api/v4/users/fc6suoon9pbbpmhrb9c967paxe/threads/read' \\\n-H 'Authorization: Bearer 9kg8nqrnxprd9jbykqeg4r51hw' \\\n"
}
]
}
},
"/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\n\n__Minimum server version__: 5.29\n\n##### Permissions\nMust be logged in as the user or have `edit_other_users` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\nuss, response := Client.UpdateThreadReadForUser(\"fc6suoon9pbbpmhrb9c967paxe\", \"fc6su111111pmhrb9c967paxe\", \"f96cv0897624352346e\" true)\n"
},
{
"lang": "Curl",
"source": "curl -X PUT 'http://localhost:8065/api/v4/users/fc6suoon9pbbpmhrb9c967paxe/threads/f96345234975624/read' \\\n-H 'Authorization: Bearer 9kg8nqrnxprd9jbykqeg4r51hw' \n"
}
]
}
},
"/users/{user_id}/teams/{team_id}/threads/{thread_id}/following": {
"put": {
"tags": [
"threads"
],
"summary": "Start following a thread",
"description": "Start following a thread\n\n__Minimum server version__: 5.29\n\n##### Permissions\nMust be logged in as the user or have `edit_other_users` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\nuss, response := Client.UpdateThreadFollowForUser(\"fc6suoon9pbbpmhrb9c967paxe\", \"fc6su111111pmhrb9c967paxe\", \"f96cv0897624352346e\" true)\n"
},
{
"lang": "Curl",
"source": "curl -X PUT 'http://localhost:8065/api/v4/users/fc6suoon9pbbpmhrb9c967paxe/threads/f96345234975624/followin' \\\n-H 'Authorization: Bearer 9kg8nqrnxprd9jbykqeg4r51hw' \\\n"
}
]
},
"delete": {
"tags": [
"threads"
],
"summary": "Stop following a thread",
"description": "Stop following a thread\n\n__Minimum server version__: 5.29\n\n##### Permissions\nMust be logged in as the user or have `edit_other_users` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\nuss, response := Client.UpdateThreadFollowForUser(\"fc6suoon9pbbpmhrb9c967paxe\", \"fc6su111111pmhrb9c967paxe\", \"f96cv0897624352346e\" false)\n"
},
{
"lang": "Curl",
"source": "curl -X DELETE 'http://localhost:8065/api/v4/users/fc6suoon9pbbpmhrb9c967paxe/threads/f96345234975624/following' \\\n-H 'Authorization: Bearer 9kg8nqrnxprd9jbykqeg4r51hw' \\\n"
}
]
}
},
"/users/{user_id}/teams/{team_id}/threads/{thread_id}": {
"get": {
"tags": [
"threads"
],
"summary": "Get a thread followed by the user",
"description": "Get a thread\n\n__Minimum server version__: 5.29\n\n##### Permissions\nMust be logged in as the user or have `edit_other_users` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\nuss, response := Client.GetUserThread(\"fc6suoon9pbbpmhrb9c967paxe\", \"fc6su111111pmhrb9c967paxe\", \"f96cv0897624352346e\")\n"
},
{
"lang": "Curl",
"source": "curl -X GET 'http://localhost:8065/api/v4/users/fc6suoon9pbbpmhrb9c967paxe/threads/f96345234975624' \\\n-H 'Authorization: Bearer 9kg8nqrnxprd9jbykqeg4r51hw' \\\n"
}
]
}
},
"/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.\n\n__Minimum server version__: 5.35\n\n##### Permissions\nMust be logged in as the user or have the `manage_system` permission.\n\n##### License\nRequires an E20 license.\n",
"operationId": "GetTeamPoliciesForUser",
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "The ID of the user. This can also be \"me\" which will point to the current user.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "page",
"in": "query",
"description": "The page to select.",
"schema": {
"type": "integer",
"default": 0
}
},
{
"name": "per_page",
"in": "query",
"description": "The number of policies per page. There is a maximum limit of 200 per page.",
"schema": {
"type": "integer",
"default": 60
}
}
],
"responses": {
"200": {
"description": "Teams for retention policy successfully retrieved.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RetentionPolicyForTeamList"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
},
"501": {
"$ref": "#/components/responses/NotImplemented"
}
}
}
},
"/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.\n\n__Minimum server version__: 5.35\n\n##### Permissions\nMust be logged in as the user or have the `manage_system` permission.\n\n##### License\nRequires an E20 license.\n",
"operationId": "GetChannelPoliciesForUser",
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "The ID of the user. This can also be \"me\" which will point to the current user.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "page",
"in": "query",
"description": "The page to select.",
"schema": {
"type": "integer",
"default": 0
}
},
{
"name": "per_page",
"in": "query",
"description": "The number of policies per page. There is a maximum limit of 200 per page.",
"schema": {
"type": "integer",
"default": 60
}
}
],
"responses": {
"200": {
"description": "Channels for retention policy successfully retrieved.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RetentionPolicyForChannelList"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
},
"501": {
"$ref": "#/components/responses/NotImplemented"
}
}
}
},
"/users/{user_id}/status": {
"get": {
"tags": [
"status"
],
"summary": "Get user status",
"description": "Get user status by id from the server.\n##### Permissions\nMust be authenticated.\n",
"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.\n##### Permissions\nMust have `edit_other_users` permission for the team.\n",
"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"
}
}
}
},
"/users/status/ids": {
"post": {
"tags": [
"status"
],
"summary": "Get user statuses by id",
"description": "Get a list of user statuses by id from the server.\n##### Permissions\nMust be authenticated.\n",
"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"
}
}
}
},
"/users/{user_id}/status/custom": {
"put": {
"tags": [
"custom_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\n##### Permissions\nMust be logged in as the user whose custom status is being updated.\n",
"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": [
"custom_status"
],
"summary": "Unsets user custom status",
"description": "Unsets a user's custom status by updating the user's props and updates the user\n##### Permissions\nMust be logged in as the user whose custom status is being removed.\n",
"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"
}
}
}
},
"/users/{user_id}/status/custom/recent": {
"delete": {
"tags": [
"custom_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.\n##### Permissions\nMust be logged in as the user whose recent custom status is being deleted.\n",
"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"
}
}
}
},
"/users/{user_id}/status/custom/recent/delete": {
"post": {
"tags": [
"custom_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.\n##### Permissions\nMust be logged in as the user whose recent custom status is being deleted.\n",
"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"
}
}
}
},
"/teams": {
"post": {
"tags": [
"teams"
],
"summary": "Create a team",
"description": "Create a new team on the system.\n##### Permissions\nMust be authenticated and have the `create_team` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nnewTeam, err := Client.CreateTeam(&model.Team{\n Name: \"teamName\",\n DisplayName: \"TeamDisplayName\",\n Type: \"O\",\n})\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$resp = $driver->getTeamModel()->createTeam([\n \"name\" => \"teamName\",\n \"display_name\" => \"TeamDisplayName\",\n \"type\" => \"O\",\n]);\n\nif ($resp->getStatusCode() == 200) {\n $newTeam = json_decode($resp->getBody());\n}\n"
}
]
},
"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.\n##### Permissions\nMust be authenticated. \"manage_system\" permission is required to show all teams.\n",
"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",
"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.\n__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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nteams, resp := Client.GetAllTeams(\"\", 0, 100)\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$resp = $driver->getTeamModel()->getTeams([\n \"page\" => 0,\n \"per_page\" => 100,\n \"include_total_count\" => false,\n]);\n\nif ($resp->getStatusCode() == 200) {\n $teams = json_decode($resp->getBody());\n}\n"
}
]
}
},
"/teams/{team_id}": {
"get": {
"tags": [
"teams"
],
"summary": "Get a team",
"description": "Get a team on the system.\n##### Permissions\nMust be authenticated and have the `view_team` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nteamID := \"4xp9fdt77pncbef59f4k1qe83o\"\n\nt, err := Client.GetTeam(teamID, \"\")\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$teamID = \"4xp9fdt77pncbef59f4k1qe83o\";\n\n$resp = $driver->getTeamModel()->getTeam($teamID);\n\nif ($resp->getStatusCode() == 200) {\n $t = json_decode($resp->getBody());\n}\n"
}
]
},
"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.\n##### Permissions\nMust have the `manage_team` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nteamID := \"4xp9fdt77pncbef59f4k1qe83o\"\ninviteID := \"qjda3stwafbgpqjaxej3k76sga\"\n\nuteam, resp := Client.UpdateTeam(&model.Team{\n Id: teamID,\n DisplayName: \"displayName\",\n Description: \"description\",\n CompanyName: \"companyName\",\n AllowedDomains: \"allowedDomains\",\n InviteId: inviteID,\n AllowOpenInvite: false,\n})\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$teamID = \"4xp9fdt77pncbef59f4k1qe83o\";\n$inviteID = \"qjda3stwafbgpqjaxej3k76sga\";\n\n$resp = $driver->getTeamModel()->updateTeam($teamID, [\n \"id\" => $teamID,\n \"display_name\" => \"displayName\",\n \"description\" => \"description\",\n \"company_name\" => \"companyName\",\n \"allowed_domains\" => \"allowedDomains\",\n \"invite_id\" => $inviteID,\n \"allow_open_invite\" => false,\n]);\n\nif ($resp->getStatusCode() == 200) {\n $uteam = json_decode($resp->getBody());\n}\n"
}
]
},
"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.\n\nOptionally 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.\n##### Permissions\nMust have the `manage_team` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nteamID := \"4xp9fdt77pncbef59f4k1qe83o\"\n\n// Non-permanent deletion\nok, resp := Client.SoftDeleteTeam(&model.Team{Id: teamID})\n\n// Permanent deletion\nok, resp := Client.PermanentDeleteTeam(&model.Team{Id: teamID})\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$teamID = \"4xp9fdt77pncbef59f4k1qe83o\";\n\n// Non-permanent deletion\n$resp = $driver->getTeamModel()->deleteTeam($teamID, [\n \"permanent\" => false,\n]);\n\n// Permanent deletion\n$resp = $driver->getTeamModel()->deleteTeam($teamID, [\n \"permanent\" => true,\n]);\n\nif ($resp->getStatusCode() == 200) {\n $ok = json_decode($resp->getBody())->status;\n}\n"
}
]
}
},
"/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.\n##### Permissions\nMust have the `manage_team` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\npatch := &model.TeamPatch{}\npatch.DisplayName = model.NewString(\"Other name\")\npatch.Description = model.NewString(\"Other description\")\npatch.CompanyName = model.NewString(\"Other company name\")\npatch.AllowOpenInvite = model.NewBool(true)\n\nteamID := \"4xp9fdt77pncbef59f4k1qe83o\"\n\nteam, resp := Client.PatchTeam(teamID, patch)\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$teamID = \"4xp9fdt77pncbef59f4k1qe83o\";\n\n$resp = $driver->getTeamModel()->patchTeam($teamID, [\n \"display_name\" => \"Other name\",\n \"description\" => \"Other description\",\n \"company_name\" => \"Other company name\",\n \"allow_open_invite\" => true,\n]);\n\nif ($resp->getStatusCode() == 200) {\n $team = json_decode($resp->getBody());\n}\n"
}
]
}
},
"/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.\n\n__Minimum server version__: 5.24\n\n##### Permissions\n`manage_team` permission for the team of the team.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\n// Update team's privacy to Public\nupdatedTeam, resp := Client.UpdateTeamPrivacy(<TEAMID>, model.TEAM_OPEN)\n\n// Update team's privacy to Private\nupdatedTeam, resp := Client.UpdateTeamPrivacy(<TEAMID>, model.TEAM_INVITE)\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n// Update team's privacy to Public\n$resp = $driver->getTeamModel()->updateTeamPrivacy(<TEAMID>, [\n \"privacy\" => \"0\",\n]);\n\n// Update team's privacy to Private\n$resp = $driver->getTeamModel()->updateTeamPrivacy(<TEAMID>, [\n \"privacy\" => \"1\",\n]);\n\nif ($resp->getStatusCode() == 200) {\n $updatedTeam = json_decode($resp->getBody());\n}\n"
}
]
}
},
"/teams/{team_id}/restore": {
"post": {
"tags": [
"teams"
],
"summary": "Restore a team",
"description": "Restore a team that was previously soft deleted.\n\n__Minimum server version__: 5.24\n\n##### Permissions\nMust have the `manage_team` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\nteamID := \"4xp9fdt77pncbef59f4k1qe83o\"\nteam, resp := Client.RestoreTeam(teamID)\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$teamID = \"4xp9fdt77pncbef59f4k1qe83o\";\n\n$resp = $driver->getTeamModel()->restoreTeam($teamID);\n\nif ($resp->getStatusCode() == 200) {\n $team = json_decode($resp->getBody());\n}\n"
}
]
}
},
"/teams/name/{name}": {
"get": {
"tags": [
"teams"
],
"summary": "Get a team by name",
"description": "Get a team based on provided name string\n##### Permissions\nMust be authenticated, team type is open and have the `view_team` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nteam, resp := Client.GetTeamByName(\"teamName\", \"\")\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$resp = $driver->getTeamModel()->getTeamByName(\"teamName\");\n\nif ($resp->getStatusCode() == 200) {\n $team = json_decode($resp->getBody());\n}\n"
}
]
}
},
"/teams/search": {
"post": {
"tags": [
"teams"
],
"summary": "Search teams",
"description": "Search teams based on search term and options provided in the request body.\n\n##### Permissions\nLogged in user only shows open teams\nLogged in user with \"manage_system\" permission shows all teams\n",
"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.\nIf this filter option is not passed then the query will remain unchanged.\n__Minimum server version__: 5.28\n"
},
"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`\nIf the filter option is not passed then the query will remain unchanged.\n__Minimum server version__: 5.28\n"
},
"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.\n__Minimum server version__: 5.35\n"
}
}
}
}
},
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nteams, resp := Client.SearchTeams(&model.TeamSearch{Term: \"searchTerm\"})\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$resp = $driver->getTeamModel()->searchTeams([\n \"term\" => \"searchTerm\"\n]);\n\nif ($resp->getStatusCode() == 200) {\n $teams = json_decode($resp->getBody())->teams;\n}\n"
}
]
}
},
"/teams/name/{name}/exists": {
"get": {
"tags": [
"teams"
],
"summary": "Check if team exists",
"description": "Check if the team exists based on a team name.\n##### Permissions\nMust be authenticated.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nexists, resp := Client.TeamExists(\"teamName\", \"\")\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$resp = $driver->getTeamModel()->checkTeamExists(\"teamName\");\n\nif ($resp->getStatusCode() == 200) {\n $exists = json_decode($resp->getBody())->exists;\n}\n"
}
]
}
},
"/users/{user_id}/teams": {
"get": {
"tags": [
"teams"
],
"summary": "Get a user's teams",
"description": "Get a list of teams that a user is on.\n##### Permissions\nMust be authenticated as the user or have the `manage_system` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nuserID := \"4xp9fdt77pncbef59f4k1qe83o\"\n\nteams, resp := Client.GetTeamsForUser(userID, \"\")\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$userID = \"4xp9fdt77pncbef59f4k1qe83o\";\n\n$resp = $driver->getTeamModel()->getUserTeams($userID);\n\nif ($resp->getStatusCode() == 200) {\n $teams = json_decode($resp->getBody());\n}\n"
}
]
}
},
"/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.\n##### Permissions\nMust be authenticated and have the `view_team` permission.\n",
"operationId": "GetTeamMembers",
"parameters": [
{
"name": "team_id",
"in": "path",
"description": "Team GUID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "page",
"in": "query",
"description": "The page to select.",
"schema": {
"type": "integer",
"default": 0
}
},
{
"name": "per_page",
"in": "query",
"description": "The number of users per page.",
"schema": {
"type": "integer",
"default": 60
}
}
],
"responses": {
"200": {
"description": "Team members retrieval successful",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TeamMember"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nteamID := \"4xp9fdt77pncbef59f4k1qe83o\"\n\nmembers, resp := Client.GetTeamMembers(teamID, 0, 100, \"\")\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$teamID = \"4xp9fdt77pncbef59f4k1qe83o\";\n\n$resp = $driver->getTeamModel()->getTeamMembers($teamID, [\n \"page\" => 0,\n \"per_page\" => 100,\n]);\n\nif ($resp->getStatusCode() == 200) {\n $members = json_decode($resp->getBody());\n}\n"
}
]
},
"post": {
"tags": [
"teams"
],
"summary": "Add user to team",
"description": "Add user to the team by user_id.\n##### Permissions\nMust be authenticated and team be open to add self. For adding another user, authenticated user must have the `add_user_to_team` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nteamID := \"4xp9fdt77pncbef59f4k1qe83o\"\nuserID := \"qjda3stwafbgpqjaxej3k76sga\"\n\nteamMember, resp := Client.AddTeamMember(teamID, userID)\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$teamID = \"4xp9fdt77pncbef59f4k1qe83o\";\n$userID = \"qjda3stwafbgpqjaxej3k76sga\";\n\n$resp = $driver->getTeamModel()->addUser($teamID, [\n \"user_id\" => $userID,\n \"team_id\" => $teamID,\n]);\n\nif ($resp->getStatusCode() == 200) {\n $teamMember = json_decode($resp->getBody());\n}\n"
}
]
}
},
"/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.\n##### Permissions\nMust be authenticated.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\ntokenID := \"qjda3stwafbgpqjaxej3k76sga\"\n\ntm, resp = Client.AddTeamMemberFromInvite(tokenID, \"\")\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$tokenID = \"qjda3stwafbgpqjaxej3k76sga\";\n\n$resp = $driver->getTeamModel()->addUserFromInvite([\n \"token\" => $tokenID\n]);\n\nif ($resp->getStatusCode() == 200) {\n $tm = json_decode($resp->getBody());\n}\n"
}
]
}
},
"/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.\n##### Permissions\nMust be authenticated. Authenticated user must have the `add_user_to_team` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nteamID := \"IJyUQLwh1CO9ahbzaQwWwc0ZnV\"\n\nuserID := \"zWEyrTZ7GZ22aBSfoX60iWryTY\"\nuserID2 := \"NqCSr5HMDZjrWS74IEmedvlOYf\"\n\ntm, resp := Client.AddTeamMembers(teamID, []string{userID, userID2})\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$teamID = \"IJyUQLwh1CO9ahbzaQwWwc0ZnV\";\n\n$userID = \"zWEyrTZ7GZ22aBSfoX60iWryTY\";\n$userID2 = \"NqCSr5HMDZjrWS74IEmedvlOYf\";\n\n$resp = $driver->getTeamModel()->addMultipleUsers($teamID, [\n [\n \"user_id\" => $userID,\n ],\n [\n \"user_id\" => $userID2,\n ],\n]);\n\nif ($resp->getStatusCode() == 200) {\n $tm = json_decode($resp->getBody());\n}\n"
}
]
}
},
"/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.\n##### Permissions\nMust be logged in as the user or have the `edit_other_users` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nuserID := \"zWEyrTZ7GZ22aBSfoX60iWryTY\"\n\nteamMembers, resp = Client.GetTeamMembersForUser(userID, \"\")\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$userID = \"zWEyrTZ7GZ22aBSfoX60iWryTY\";\n\n$resp = $driver->getTeamModel()->getTeamMembersForUser($userID);\n\nif ($resp->getStatusCode() == 200) {\n $teamMembers = json_decode($resp->getBody());\n}\n"
}
]
}
},
"/teams/{team_id}/members/{user_id}": {
"get": {
"tags": [
"teams"
],
"summary": "Get a team member",
"description": "Get a team member on the system.\n##### Permissions\nMust be authenticated and have the `view_team` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nteamID := \"zWEyrTZ7GZ22aBSfoX60iWryTY\"\nuserID := \"NqCSr5HMDZjrWS74IEmedvlOYf\"\n\nteamMember, resp = Client.GetTeamMember(teamID, userID, \"\")\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$teamID = \"zWEyrTZ7GZ22aBSfoX60iWryTY\";\n$userID = \"NqCSr5HMDZjrWS74IEmedvlOYf\";\n\n$resp = $driver->getTeamModel()->getTeamMember($teamID, $userID);\n\nif ($resp->getStatusCode() == 200) {\n $teamMember = json_decode($resp->getBody());\n}\n"
}
]
},
"delete": {
"tags": [
"teams"
],
"summary": "Remove user from team",
"description": "Delete the team member object for a user, effectively removing them from a team.\n##### Permissions\nMust be logged in as the user or have the `remove_user_from_team` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nteamID := \"zWEyrTZ7GZ22aBSfoX60iWryTY\"\nuserID := \"NqCSr5HMDZjrWS74IEmedvlOYf\"\n\nok, resp = Client.RemoveTeamMember(teamID, userID)\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$teamID = \"zWEyrTZ7GZ22aBSfoX60iWryTY\";\n$userID = \"NqCSr5HMDZjrWS74IEmedvlOYf\";\n\n$resp = $driver->getTeamModel()->removeUser($teamID, $userID);\n\nif ($resp->getStatusCode() == 200) {\n $ok = json_decode($resp->getBody())->status;\n}\n"
}
]
}
},
"/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.\n##### Permissions\nMust have `view_team` permission for the team.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nteamID := zWEyrTZ7GZ22aBSfoX60iWryTY\n\nuserID := \"NqCSr5HMDZjrWS74IEmedvlOYf\"\nuserID2 := \"UAFalLvtKwNKABAnmwR7uGB5md\"\n\ntm, resp := Client.GetTeamMembersByIds(teamID, []string{userID, userID2})\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$teamID = \"zWEyrTZ7GZ22aBSfoX60iWryTY\";\n\n$userID = \"NqCSr5HMDZjrWS74IEmedvlOYf\";\n$userID2 = \"UAFalLvtKwNKABAnmwR7uGB5md\";\n\n$resp = $driver->getTeamModel()->getTeamMembersByIds($teamID, [\n $userID,\n $userID2,\n]);\n\nif ($resp->getStatusCode() == 200) {\n $tm = json_decode($resp->getBody());\n}\n"
}
]
}
},
"/teams/{team_id}/stats": {
"get": {
"tags": [
"teams"
],
"summary": "Get a team stats",
"description": "Get a team stats on the system.\n##### Permissions\nMust be authenticated and have the `view_team` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nteamID := \"zWEyrTZ7GZ22aBSfoX60iWryTY\"\n\nstats, resp := Client.GetTeamStats(teamID, \"\")\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$teamID = \"zWEyrTZ7GZ22aBSfoX60iWryTY\";\n\n$resp = $driver->getTeamModel()->getTeamStats($teamID);\n\nif ($resp->getStatusCode() == 200) {\n $stats = json_decode($resp->getBody());\n}\n"
}
]
}
},
"/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\n##### Permissions\nMust be authenticated and have the `manage_team` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nteamID := \"zWEyrTZ7GZ22aBSfoX60iWryTY\"\n\nteam, resp := Client.RegenerateTeamInviteId(teamID)\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$teamID = \"zWEyrTZ7GZ22aBSfoX60iWryTY\";\n\n$resp = $driver->getTeamModel()->regenerateInviteID($teamID);\n\nif ($resp->getStatusCode() == 200) {\n $team = json_decode($resp->getBody());\n}\n"
}
]
}
},
"/teams/{team_id}/image": {
"get": {
"tags": [
"teams"
],
"summary": "Get the team icon",
"description": "Get the team icon of the team.\n\n__Minimum server version__: 4.9\n\n##### Permissions\nUser must be authenticated. In addition, team must be open or the user must have the `view_team` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nteamID := \"zWEyrTZ7GZ22aBSfoX60iWryTY\"\n\nicon, resp = Client.GetTeamIcon(teamID, \"\")\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$teamID = \"zWEyrTZ7GZ22aBSfoX60iWryTY\";\n\n$resp = $driver->getTeamModel()->getTeamIcon($teamID);\n\nif ($resp->getStatusCode() == 200) {\n $icon = json_decode($resp->getBody());\n}\n"
}
]
},
"post": {
"tags": [
"teams"
],
"summary": "Sets the team icon",
"description": "Sets the team icon for the team.\n\n__Minimum server version__: 4.9\n\n##### Permissions\nMust be authenticated and have the `manage_team` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import (\n \"io/ioutil\"\n \"log\"\n\n \"github.com/mattermost/mattermost-server/v5/model\"\n)\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\ndata, err := ioutil.ReadFile(\"icon.png\")\nif err != nil {\n log.Fatal(err)\n}\n\nteamID := \"zWEyrTZ7GZ22aBSfoX60iWryTY\"\n\nok, resp := Client.SetTeamIcon(teamID, data)\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$teamID = \"zWEyrTZ7GZ22aBSfoX60iWryTY\";\n$resource = fopen(\"icon.png\", 'rb');\n\nif ($resource === false) {\n throw new \\Exeption(\"Failure.\");\n}\n\n$data = new \\GuzzleHttp\\Psr7\\Stream($resource);\n\n$resp = $driver->getTeamModel()->setTeamIcon($teamID, [\n \"image\" => $data,\n]);\n\nfclose($resource);\n\nif ($resp->getStatusCode() == 200) {\n $ok = json_decode($resp->getBody())->status;\n}\n"
}
]
},
"delete": {
"tags": [
"teams"
],
"summary": "Remove the team icon",
"description": "Remove the team icon for the team.\n\n__Minimum server version__: 4.10\n\n##### Permissions\nMust be authenticated and have the `manage_team` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nteamID := \"zWEyrTZ7GZ22aBSfoX60iWryTY\"\n\nok, resp = Client.RemoveTeamIcon(teamID)\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$teamID = \"zWEyrTZ7GZ22aBSfoX60iWryTY\";\n\n$resp = $driver->getTeamModel()->removeTeamIcon($teamID);\n\nif ($resp->getStatusCode() == 200) {\n $ok = json_decode($resp->getBody())->status;\n}\n"
}
]
}
},
"/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.\n##### Permissions\nMust be authenticated and have the `manage_team_roles` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nteamID := \"zWEyrTZ7GZ22aBSfoX60iWryTY\"\nuserID := \"NqCSr5HMDZjrWS74IEmedvlOYf\"\n\nok, resp := Client.UpdateTeamMemberRoles(teamID, userID, \"team_user team_admin\")\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$teamID = \"zWEyrTZ7GZ22aBSfoX60iWryTY\";\n$userID = \"NqCSr5HMDZjrWS74IEmedvlOYf\";\n\n$resp = $driver->getTeamModel()->updateTeamMemberRoles($teamID, $userID, [\n \"roles\" => \"team_user team_admin\",\n]);\n\nif ($resp->getStatusCode() == 200) {\n $ok = json_decode($resp->getBody())->status;\n}\n"
}
]
}
},
"/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.\n\n__Minimum server version__: 5.0\n\n##### Permissions\nMust be authenticated and have the `manage_team_roles` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nteamID := \"zWEyrTZ7GZ22aBSfoX60iWryTY\"\nuserID := \"NqCSr5HMDZjrWS74IEmedvlOYf\"\n\nok, resp := Client.UpdateTeamMemberSchemeRoles(teamID, userID, &model.SchemeRoles{\n SchemeAdmin: true,\n SchemeUser: true,\n})\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$teamID = \"zWEyrTZ7GZ22aBSfoX60iWryTY\";\n$userID = \"NqCSr5HMDZjrWS74IEmedvlOYf\";\n\n$resp = $driver->getTeamModel()->updateSchemeDerivedRolesOfMember($teamID, $userID, [\n \"scheme_admin\" => true,\n \"scheme_user\" => true,\n]);\n\nif ($resp->getStatusCode() == 200) {\n $ok = json_decode($resp->getBody())->status;\n}\n"
}
]
}
},
"/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.\n##### Permissions\nMust be logged in.\n",
"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"
}
}
],
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nuserID := \"NqCSr5HMDZjrWS74IEmedvlOYf\"\nteamID := \"zWEyrTZ7GZ22aBSfoX60iWryTY\"\n\nteams, resp := Client.GetTeamsUnreadForUser(userID, teamID)\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$userID = \"NqCSr5HMDZjrWS74IEmedvlOYf\";\n$teamID = \"zWEyrTZ7GZ22aBSfoX60iWryTY\";\n\n$resp = $driver->getTeamModel()->getUserTotalUnreadMessagesFromTeams($userID, [\n \"exclude_team\" => $teamID,\n]);\n\nif ($resp->getStatusCode() == 200) {\n $teams = json_decode($resp->getBody());\n}\n"
}
]
}
},
"/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.\n##### Permissions\nMust be the user or have `edit_other_users` permission and have `view_team` permission for the team.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nuserID := \"NqCSr5HMDZjrWS74IEmedvlOYf\"\nteamID := \"zWEyrTZ7GZ22aBSfoX60iWryTY\"\n\nteamUnread, resp := Client.GetTeamUnread(userID, teamID)\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$userID = \"NqCSr5HMDZjrWS74IEmedvlOYf\";\n$teamID = \"zWEyrTZ7GZ22aBSfoX60iWryTY\";\n\n$resp = $driver->getTeamModel()->getUserTotalUnreadMessagesFromTeam($userID, $teamID);\n\nif ($resp->getStatusCode() == 200) {\n $teamUnread = json_decode($resp->getBody());\n}\n"
}
]
}
},
"/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.\n\nThe 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.\n##### Permissions\nMust have `invite_user` and `add_user_to_team` permissions for the team.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nteamID := \"zWEyrTZ7GZ22aBSfoX60iWryTY\"\n\nok, resp := Client.InviteUsersToTeam(teamID, []string{\"test@domain.com\", \"test2@domain.com\"})\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$teamID = \"zWEyrTZ7GZ22aBSfoX60iWryTY\";\n\n$resp = $driver->getTeamModel()->inviteUsersByEmail($teamID, [\n \"test@domain.com\",\n \"test2@domain.com\",\n]);\n\nif ($resp->getStatusCode() == 200) {\n $ok = json_decode($resp->getBody())->status;\n}\n"
}
]
}
},
"/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.\n\nThe 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.\n\n__Minimum server version__: 5.16\n\n##### Permissions\nMust have `invite_guest` permission for the team.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nteamID := \"zWEyrTZ7GZ22aBSfoX60iWryTY\"\nchannel1ID := \"wu6wyxm9spgwtjaycjrcihnqtr\"\nchannel2ID := \"ymzsgjw1tprniqtzyb7g3cmuuc\"\n\nok, resp := Client.InviteGuestsToTeam(teamID, []string{\"test@domain.com\", \"test2@domain.com\"}, []string{channel1ID, channel2ID}, \"Please join to our mattermost team to keep working in the project\")\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$teamID = \"zWEyrTZ7GZ22aBSfoX60iWryTY\";\n\n$channel1ID = \"wu6wyxm9spgwtjaycjrcihnqtr\";\n$channel2ID = \"ymzsgjw1tprniqtzyb7g3cmuuc\";\n\n$resp = $driver->getTeamModel()->inviteGuestsByEmail($teamID, [\n \"emails\" => [\"test@domain.com\", \"test2@domain.com\"],\n \"channels\" => [$channel1ID, $channel2ID],\n \"message\" => \"Please join to our mattermost team to keep working in the project\",\n]);\n\nif ($resp->getStatusCode() == 200) {\n $ok = json_decode($resp->getBody())->status;\n}\n"
}
]
}
},
"/teams/invites/email": {
"delete": {
"tags": [
"teams"
],
"summary": "Invalidate active email invitations",
"description": "Invalidate active email invitations that have not been accepted by the user.\n##### Permissions\nMust have `sysconsole_write_authentication` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nok, resp := Client.InvalidateEmailInvites()\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$resp = $driver->getTeamModel()->invalidateActiveEmailInvitations();\n\nif ($resp->getStatusCode() == 200) {\n $ok = json_decode($resp->getBody())->status;\n}\n"
}
]
}
},
"/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.\n##### Permissions\nMust have `permission_import_team` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import (\n \"encoding/binary\"\n \"io/ioutil\"\n \"log\"\n\n \"github.com/mattermost/mattermost-server/v5/model\"\n)\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\ndata, err = ioutil.ReadFile(\"to_import.zip\")\nif err != nil && len(data) == 0 {\n log.Fatal(\"Error while reading file.\")\n}\n\nteamID := \"zWEyrTZ7GZ22aBSfoX60iWryTY\"\n\nfileResp, resp := Client.ImportTeam(data, binary.Size(data), \"slack\", \"to_import.zip\", teamID)\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$teamID = \"zWEyrTZ7GZ22aBSfoX60iWryTY\";\n$resource = fopen(\"to_import.zip\", 'rb');\n\nif ($resource === false) {\n throw new \\Exeption(\"Error while reading file.\");\n}\n\n$data = new \\GuzzleHttp\\Psr7\\Stream($resource);\n\n$resp = $driver->getTeamModel()->importTeamFromOtherApplication($teamID, [\n \"file\" => $data,\n \"filesize\" => $data->getSize(),\n \"importFrom\" => \"slack\",\n]);\n\nfclose($resource);\n\nif ($resp->getStatusCode() == 200) {\n $fileResp = json_decode($resp->getBody())->results;\n}\n"
}
]
}
},
"/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.\n\n__Minimum server version__: 4.0\n\n##### Permissions\nNo authentication required.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\n\ninviteID := \"zWEyrTZ7GZ22aBSfoX60iWryTY\"\n\nteam, resp = Client.GetTeamInviteInfo(inviteID)\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$inviteID = \"zWEyrTZ7GZ22aBSfoX60iWryTY\";\n\n$resp = $driver->getTeamModel()->getInviteInfoForTeam($inviteID);\n\nif ($resp->getStatusCode() == 200) {\n $team = json_decode($resp->getBody());\n}\n"
}
]
}
},
"/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.\n\n##### Permissions\nMust have `manage_system` permission.\n\n__Minimum server version__: 5.0\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nteamID := \"4xp9fdt77pncbef59f4k1qe83o\"\nschemeID := \"qjda3stwafbgpqjaxej3k76sga\"\n\nok, resp := UpdateTeamScheme(teamID, schemeID)\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$teamID = \"4xp9fdt77pncbef59f4k1qe83o\";\n$schemeID = \"qjda3stwafbgpqjaxej3k76sga\";\n\n$resp = $driver->getTeamModel()->setTeamScheme($teamID, [\n \"scheme_id\" => $schemeID,\n]);\n\nif ($resp->getStatusCode() == 200) {\n $ok = json_decode($resp->getBody())->status;\n}\n"
},
{
"lang": "curl",
"source": "curl -X PUT \\\n https://your-mattermost-url.com/api/v4/teams/4xp9fdt77pncbef59f4k1qe83o/scheme \\\n -H 'Authorization: Bearer frn8fu5rtpyc5m4xy6q3oj4yur' \\\n -H 'Content-Type: application/json' \\\n -d '{\"scheme_id\": \"qjda3stwafbgpqjaxej3k76sga\"}'\n"
}
]
}
},
"/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.\nEach user object contains an array of group objects representing the group memberships for that user.\nEach user object contains the boolean fields `scheme_guest`, `scheme_user`, and `scheme_admin` representing the roles that user has for the given team.\n\n##### Permissions\nMust have `manage_system` permission.\n\n__Minimum server version__: 5.14\n",
"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"
}
},
"x-code-samples": [
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$teamID = \"fcnst115y3y7xmzzp5uq34u8ce\";\n\n$groupID = \"eoezijg8zffgjmch8icy5bjd1e\";\n$groupID2 = \"ugaw6wjc3tfxpcr1eq5u5k8dhe\";\n\n$resp = $driver->getTeamModel()->getTeamMembersMinusGroupMembers($teamID, [\n \"group_ids\" => [$groupID, $groupID2],\n \"page\" => 0,\n \"per_page\" => 100,\n]);\n\nif ($resp->getStatusCode() == 200) {\n $members = json_decode($resp->getBody());\n}\n"
},
{
"lang": "curl",
"source": "curl 'http://your-mattermost-url.com/api/v4/teams/fcnst115y3y7xmzzp5uq34u8ce/members_minus_group_members?group_ids=eoezijg8zffgjmch8icy5bjd1e,ugaw6wjc3tfxpcr1eq5u5k8dhe&page=0&per_page=100' \\\n -H 'Authorization: Bearer mq8rrfxpdfyafbnw3qfmhwkx6c' \\\n -H 'Content-Type: application/json' \\\n -H 'X-Requested-With: XMLHttpRequest'\n"
}
]
}
},
"/channels": {
"get": {
"tags": [
"channels"
],
"summary": "Get a list of all channels",
"description": "##### Permissions\n`manage_system`\n",
"operationId": "GetAllChannels",
"parameters": [
{
"name": "not_associated_to_group",
"in": "query",
"description": "Group GUID",
"schema": {
"type": "string"
}
},
{
"name": "page",
"in": "query",
"schema": {
"type": "integer",
"default": 0
}
},
{
"name": "per_page",
"in": "query",
"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": "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.\n__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.\n##### Permissions\nIf creating a public channel, `create_public_channel` permission is required. If creating a private channel, `create_private_channel` permission is required.\n",
"operationId": "CreateChannel",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"name",
"display_name",
"type",
"team_id"
],
"properties": {
"team_id": {
"type": "string",
"description": "The team ID of the team to create the channel on"
},
"name": {
"type": "string",
"description": "The unique handle for the channel, will be present in the channel URL"
},
"display_name": {
"type": "string",
"description": "The non-unique UI name for the channel"
},
"purpose": {
"type": "string",
"description": "A short description of the purpose of the channel"
},
"header": {
"type": "string",
"description": "Markdown-formatted text to display in the header of the channel"
},
"type": {
"type": "string",
"description": "'O' for a public channel, 'P' for a private channel"
}
}
}
}
},
"description": "Channel object to be created",
"required": true
},
"responses": {
"201": {
"description": "Channel creation successful",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Channel"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nchannel := &model.Channel{DisplayName: <YOUR CHANNEL DISPLAYNAME>, Name: <YOUR CHANNEL NAME>, Type: <CHANNEL TYPE OPEN/PRIVATE>, TeamId: <YOUR TEAM ID>}\n\n// CreateChannel\nrchannel, resp := Client.CreateChannel(channel)\n"
}
]
}
},
"/channels/direct": {
"post": {
"tags": [
"channels"
],
"summary": "Create a direct message channel",
"description": "Create a new direct message channel between two users.\n##### Permissions\nMust be one of the two users and have `create_direct_channel` permission. Having the `manage_system` permission voids the previous requirements.\n",
"operationId": "CreateDirectChannel",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 2,
"maxItems": 2
}
}
},
"description": "The two user ids to be in the direct message",
"required": true
},
"responses": {
"201": {
"description": "Direct channel creation successful",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Channel"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\n// CreateDirectChannel\ndm, resp := Client.CreateDirectChannel(<ID OF User1>, <ID OF User2>)\n"
}
]
}
},
"/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.\n##### Permissions\nMust have `create_group_channel` permission.\n",
"operationId": "CreateGroupChannel",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"description": "User ids to be in the group message channel",
"required": true
},
"responses": {
"201": {
"description": "Group channel creation successful",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Channel"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nuserIds := []string{<ID OF User1>, <ID OF User2>, <ID OF User3> ...}\n\n// CreateGroupChannel\nrgc, resp := Client.CreateGroupChannel(userIds)\n"
}
]
}
},
"/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\nthe channel.\n\nConfigured 'default' channels (ex Town Square and Off-Topic) can be excluded from the results\nwith the `exclude_default_channels` boolean parameter.\n\nChannels that are associated (via GroupChannel records) to a given group can be excluded from the results\nwith the `not_associated_to_group` parameter and a group id string.\n",
"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.\n",
"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",
"description": "Filters results to channels belonging to the given team ids\n\n__Minimum server version__: 5.26\n"
},
"group_constrained": {
"type": "boolean",
"description": "Filters results to only return channels constrained to a group\n\n__Minimum server version__: 5.26\n"
},
"exclude_group_constrained": {
"type": "boolean",
"description": "Filters results to exclude channels constrained to a group\n\n__Minimum server version__: 5.26\n"
},
"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\n\n__Minimum server version__: 5.26\n"
},
"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\n\n__Minimum server version__: 5.26\n"
},
"deleted": {
"type": "boolean",
"description": "Filters results to only return deleted / archived channels\n\n__Minimum server version__: 5.26\n"
},
"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.\n__Minimum server version__: 5.35\n"
}
}
}
}
},
"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"
}
}
}
},
"/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.\n\n__Minimum server version__: 5.14\n",
"operationId": "SearchGroupChannels",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"term"
],
"properties": {
"term": {
"description": "The search term to match against the members' usernames of the group channels",
"type": "string"
}
}
}
}
},
"description": "Search criteria",
"required": true
},
"responses": {
"200": {
"description": "Channels search successful",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Channel"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nsearch := &model.ChannelSearch{Term: <MEMBER USERNAME>}\n\n// SearchGroupChannels\nchannels, resp := Client.SearchGroupChannels(search)\n"
}
]
}
},
"/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.\n##### Permissions\n`view_team` for the team the channels are on.\n",
"operationId": "GetPublicChannelsByIdsForTeam",
"parameters": [
{
"name": "team_id",
"in": "path",
"description": "Team GUID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"description": "List of channel ids",
"required": true
},
"responses": {
"200": {
"description": "Channel list retrieval successful",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Channel"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nchannelIds := []string{<ID OF CHANNEL1>, <ID OF CHANNEL2>, ...}\n\n// GetPublicChannelsByIdsForTeam\nchannels, resp := Client.GetPublicChannelsByIdsForTeam(<TEAMID>, channelIds)\n"
}
]
}
},
"/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.\n\n__Minimum server version__: 5.6\n\n##### Permissions\nMust have the `read_channel` permission.\n",
"operationId": "GetChannelMembersTimezones",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "Channel GUID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Timezone retrieval successful",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\n// GetChannelStats\nstats, resp := Client.GetChannelTimezones(<CHANNELID>)\n"
}
]
}
},
"/channels/{channel_id}": {
"get": {
"tags": [
"channels"
],
"summary": "Get a channel",
"description": "Get channel from the provided channel id string.\n##### Permissions\n`read_channel` permission for the channel.\n",
"operationId": "GetChannel",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "Channel GUID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Channel retrieval successful",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Channel"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\n// GetChannel\nchannel, resp := Client.GetChannel(<CHANNELID>, \"\")\n"
}
]
},
"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.\n##### Permissions\nIf updating a public channel, `manage_public_channel_members` permission is required. If updating a private channel, `manage_private_channel_members` permission is required.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nchannel := &model.Channel{DisplayName: <YOUR CHANNEL NEW DISPLAYNAME>, ChannelId: <CHANNELID>, TeamId: <YOUR TEAM ID>}\n\n// UpdateChannel\nupdatedChannel, resp := Client.UpdateChannel(channel)\n"
}
]
},
"delete": {
"tags": [
"channels"
],
"summary": "Delete a channel",
"description": "Soft deletes a channel, by marking the channel as deleted in the database. Soft deleted channels will not be accessible in the user interface. Direct and group message channels cannot be deleted.\n\nAs 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.\n\n##### Permissions\n`delete_public_channel` permission if the channel is public,\n`delete_private_channel` permission if the channel is private,\nor have `manage_system` permission.\n",
"operationId": "DeleteChannel",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "Channel GUID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Channel deletion successful",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StatusOK"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\n// DeleteChannel\npass, resp := Client.DeleteChannel(<CHANNELID>)\n"
}
]
}
},
"/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.\n##### Permissions\nIf updating a public channel, `manage_public_channel_members` permission is required. If updating a private channel, `manage_private_channel_members` permission is required.\n",
"operationId": "PatchChannel",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "Channel GUID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The unique handle for the channel, will be present in the channel URL"
},
"display_name": {
"type": "string",
"description": "The non-unique UI name for the channel"
},
"purpose": {
"type": "string",
"description": "A short description of the purpose of the channel"
},
"header": {
"type": "string",
"description": "Markdown-formatted text to display in the header of the channel"
}
}
}
}
},
"description": "Channel object to be updated",
"required": true
},
"responses": {
"200": {
"description": "Channel patch successful",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Channel"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\npatch := &model.ChannelPatch{\n Name: new(string),\n DisplayName: new(string),\n Header: new(string),\n Purpose: new(string),\n}\n*patch.Name = \"<SOME_NEW_NAME>\"\n*patch.DisplayName = \"<SOME_NEW_DISPLAYNAME>\"\n*patch.Header = \"<SOME_NEW_HEADER>\"\n*patch.Purpose = \"<SOME_NEW_PURPOSE>\"\n\n// PatchChannel\nchannel, resp := Client.PatchChannel(<CHANNELID>, patch)\n"
}
]
}
},
"/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.\n\n__Minimum server version__: 5.16\n\n##### Permissions\n`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.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\n// Update channel's privacy to Public\nupdatedChannel, resp := Client.UpdateChannelPrivacy(<CHANNELID>, model.CHANNEL_OPEN)\n\n// Update channel's privacy to Private\nupdatedChannel, resp := Client.UpdateChannelPrivacy(<CHANNELID>, model.CHANNEL_PRIVATE)\n"
}
]
}
},
"/channels/{channel_id}/restore": {
"post": {
"tags": [
"channels"
],
"summary": "Restore a channel",
"description": "Restore channel from the provided channel id string.\n\n__Minimum server version__: 3.10\n\n##### Permissions\n`manage_team` permission for the team of the channel.\n",
"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"
}
}
}
},
"/channels/{channel_id}/move": {
"post": {
"tags": [
"channels"
],
"summary": "Move a channel",
"description": "Move a channel to another team.\n\n__Minimum server version__: 5.26\n\n##### Permissions\n\nMust have `manage_system` permission.\n",
"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"
}
}
}
},
"/channels/{channel_id}/stats": {
"get": {
"tags": [
"channels"
],
"summary": "Get channel statistics",
"description": "Get statistics for a channel.\n##### Permissions\nMust have the `read_channel` permission.\n",
"operationId": "GetChannelStats",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "Channel GUID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Channel statistics retrieval successful",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChannelStats"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\n// GetChannelStats\nstats, resp := Client.GetChannelStats(<CHANNELID>)\n"
}
]
}
},
"/channels/{channel_id}/pinned": {
"get": {
"tags": [
"channels"
],
"summary": "Get a channel's pinned posts",
"description": "Get a list of pinned posts for channel.",
"operationId": "GetPinnedPosts",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "Channel GUID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "The list of channel pinned posts",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PostList"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\n// GetPinnedPosts\nposts, resp := Client.GetPinnedPosts(<CHANNELID>, \"\")\n"
}
]
}
},
"/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.\n##### Permissions\nMust be authenticated and have the `list_team_channels` permission.\n",
"operationId": "GetPublicChannelsForTeam",
"parameters": [
{
"name": "team_id",
"in": "path",
"description": "Team GUID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "page",
"in": "query",
"description": "The page to select.",
"schema": {
"type": "integer",
"default": 0
}
},
{
"name": "per_page",
"in": "query",
"description": "The number of public channels per page.",
"schema": {
"type": "integer",
"default": 60
}
}
],
"responses": {
"200": {
"description": "Channels retrieval successful",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Channel"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n// GetPublicChannelsForTeam\nchannels, resp := Client.GetPublicChannelsForTeam(<TEAMID>, 0, 100, \"\")\n"
}
]
}
},
"/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\nparameters - team_id, page and per_page.\n\n__Minimum server version__: 5.26\n\n##### Permissions\nMust have `manage_system` permission.\n",
"operationId": "GetPrivateChannelsForTeam",
"parameters": [
{
"name": "team_id",
"in": "path",
"description": "Team GUID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "page",
"in": "query",
"description": "The page to select.",
"schema": {
"type": "integer",
"default": 0
}
},
{
"name": "per_page",
"in": "query",
"description": "The number of private channels per page.",
"schema": {
"type": "integer",
"default": 60
}
}
],
"responses": {
"200": {
"description": "Channels retrieval successful",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Channel"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n// GetPrivateChannelsForTeam\nchannels, resp := Client.GetPrivateChannelsForTeam(<TEAMID>, 0, 100, \"\")\n"
}
]
}
},
"/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.\n\n__Minimum server version__: 3.10\n",
"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"
}
}
}
},
"/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.\n\n__Minimum server version__: 4.7\n\n##### Permissions\nMust have the `list_team_channels` permission.\n",
"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"
}
}
}
},
"/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.\n\n__Minimum server version__: 5.4\n\n##### Permissions\nMust have the `list_team_channels` permission.\n",
"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"
}
}
}
},
"/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.\n##### Permissions\nMust have the `list_team_channels` permission.\n\nIn 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.\n",
"operationId": "SearchChannels",
"parameters": [
{
"name": "team_id",
"in": "path",
"description": "Team GUID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"term"
],
"properties": {
"term": {
"description": "The search term to match against the name or display name of channels",
"type": "string"
}
}
}
}
},
"description": "Search criteria",
"required": true
},
"responses": {
"201": {
"description": "Channels search successful",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Channel"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nsearch := &model.ChannelSearch{Term: <CHANNEL DISPLAYNAME>}\n\n// SearchChannels\nchannels, resp := Client.SearchChannels(<TEAMID>, search)\n"
}
]
}
},
"/teams/{team_id}/channels/search_archived": {
"post": {
"tags": [
"channels"
],
"summary": "Search archived channels",
"description": "Search archived channels on a team based on the search term provided in the request body.\n\n__Minimum server version__: 5.18\n\n##### Permissions\nMust have the `list_team_channels` permission.\n\nIn server version 5.18 and later, a user without the `list_team_channels` permission will be able to use this endpoint, with the search results limited to the channels that the user is a member of.\n",
"operationId": "SearchArchivedChannels",
"parameters": [
{
"name": "team_id",
"in": "path",
"description": "Team GUID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"term"
],
"properties": {
"term": {
"description": "The search term to match against the name or display name of archived channels",
"type": "string"
}
}
}
}
},
"description": "Search criteria",
"required": true
},
"responses": {
"201": {
"description": "Channels search successful",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Channel"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nsearch := &model.ChannelSearch{Term: <CHANNEL DISPLAYNAME>}\n\n// SearchChannels\nchannels, resp := Client.SearchArchivedChannels(<TEAMID>, search)\n"
}
]
}
},
"/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.\n##### Permissions\n`read_channel` permission for the channel.\n",
"operationId": "GetChannelByName",
"parameters": [
{
"name": "team_id",
"in": "path",
"description": "Team GUID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "channel_name",
"in": "path",
"description": "Channel Name",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "include_deleted",
"in": "query",
"description": "Defines if deleted channels should be returned or not (Mattermost Server 5.26.0+)",
"schema": {
"type": "boolean",
"default": false
}
}
],
"responses": {
"200": {
"description": "Channel retrieval successful",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Channel"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\n// GetChannelByName\nchannel, resp := Client.GetChannelByName(<CHANNEL NAME>, <TEAMID>, \"\")\n"
}
]
}
},
"/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.\n##### Permissions\n`read_channel` permission for the channel.\n",
"operationId": "GetChannelByNameForTeamName",
"parameters": [
{
"name": "team_name",
"in": "path",
"description": "Team Name",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "channel_name",
"in": "path",
"description": "Channel Name",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "include_deleted",
"in": "query",
"description": "Defines if deleted channels should be returned or not (Mattermost Server 5.26.0+)",
"schema": {
"type": "boolean",
"default": false
}
}
],
"responses": {
"200": {
"description": "Channel retrieval successful",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Channel"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\n// GetChannelByNameForTeamName\nchannel, resp = Client.GetChannelByNameForTeamName(<CHANNEL NAME>, <TEAM NAME>, \"\")\n"
}
]
}
},
"/channels/{channel_id}/members": {
"get": {
"tags": [
"channels"
],
"summary": "Get channel members",
"description": "Get a page of members for a channel.\n##### Permissions\n`read_channel` permission for the channel.\n",
"operationId": "GetChannelMembers",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "Channel GUID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "page",
"in": "query",
"description": "The page to select.",
"schema": {
"type": "integer",
"default": 0
}
},
{
"name": "per_page",
"in": "query",
"description": "The number of members per page. There is a maximum limit of 200 members.",
"schema": {
"type": "integer",
"default": 60
}
}
],
"responses": {
"200": {
"description": "Channel members retrieval successful",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ChannelMember"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\n// GetChannelMembers\nmembers, resp := Client.GetChannelMembers(th.BasicChannel.Id, 0, 60, \"\")\n"
}
]
},
"post": {
"tags": [
"channels"
],
"summary": "Add user to channel",
"description": "Add a user to a channel by creating a channel member object.",
"operationId": "AddChannelMember",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "The channel ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"user_id"
],
"properties": {
"user_id": {
"type": "string",
"description": "The ID of user to add into the channel"
},
"post_root_id": {
"type": "string",
"description": "The ID of root post where link to add channel member originates"
}
}
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Channel member creation successful",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChannelMember"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\n// AddChannelMember\ncm, resp := Client.AddChannelMember(<CHANNEL ID>, <ID OF USER TO ADD>)\n\n// AddChannelMemberWithRootId\ncm, resp := Client.AddChannelMemberWithRootId(<CHANNEL ID>, <ID OF USER TO ADD>, <POST ROOT ID>)\n"
}
]
}
},
"/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.\n##### Permissions\nMust have the `read_channel` permission.\n",
"operationId": "GetChannelMembersByIds",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "Channel GUID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"description": "List of user ids",
"required": true
},
"responses": {
"200": {
"description": "Channel member list retrieval successful",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ChannelMember"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nusersIds := []string{<Id of User1>, <Id of User2>, ...}\n\n// GetChannelMembersByIds\ncm, resp := Client.GetChannelMembersByIds(<CHANNELID>, usersIds)\n"
}
]
}
},
"/channels/{channel_id}/members/{user_id}": {
"get": {
"tags": [
"channels"
],
"summary": "Get channel member",
"description": "Get a channel member.\n##### Permissions\n`read_channel` permission for the channel.\n",
"operationId": "GetChannelMember",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "Channel GUID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "user_id",
"in": "path",
"description": "User GUID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Channel member retrieval successful",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChannelMember"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\n// GetChannelMember\nmember, resp := Client.GetChannelMember(<CHANNELID>, <USERID>, \"\")\n"
}
]
},
"delete": {
"tags": [
"channels"
],
"summary": "Remove user from channel",
"description": "Delete a channel member, effectively removing them from a channel.\n\nIn server version 5.3 and later, channel members can only be deleted from public or private channels.\n##### Permissions\n`manage_public_channel_members` permission if the channel is public.\n`manage_private_channel_members` permission if the channel is private.\n",
"operationId": "RemoveUserFromChannel",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "Channel GUID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "user_id",
"in": "path",
"description": "User GUID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Channel member deletion successful",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StatusOK"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\n// RemoveUserFromChannel\npass, resp := Client.RemoveUserFromChannel(<CHANNELID>, <USERID>)\n"
}
]
}
},
"/channels/{channel_id}/members/{user_id}/roles": {
"put": {
"tags": [
"channels"
],
"summary": "Update channel roles",
"description": "Update a user's roles for a channel.\n##### Permissions\nMust have `manage_channel_roles` permission for the channel.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\n// UpdateChannelRoles\npass, resp := Client.UpdateChannelRoles(<CHANNELID>, <USERIDTOPROMOTE>, \"channel_admin channel_user\")\n"
}
]
}
},
"/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.\n__Minimum server version__: 5.0\n##### Permissions\nMust be authenticated and have the `manage_channel_roles` permission.\n",
"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"
}
}
}
},
"/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.\n##### Permissions\nMust be logged in as the user or have `edit_other_users` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nprops := map[string]string{}\nprops[model.DESKTOP_NOTIFY_PROP] = model.CHANNEL_NOTIFY_MENTION\nprops[model.MARK_UNREAD_NOTIFY_PROP] = model.CHANNEL_MARK_UNREAD_MENTION\n\n// UpdateChannelNotifyProps\npass, resp := Client.UpdateChannelNotifyProps(<CHANNELID>, <USERID>, props)\n"
}
]
}
},
"/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.\n##### Permissions\nMust be logged in as user or have `edit_other_users` permission.\n\n__Response only includes `last_viewed_at_times` in Mattermost server 4.3 and newer.__\n",
"operationId": "ViewChannel",
"parameters": [
{
"in": "path",
"name": "user_id",
"description": "User ID to perform the view action for",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"channel_id"
],
"properties": {
"channel_id": {
"type": "string",
"description": "The channel ID that is being viewed. Use a blank string to indicate that all channels have lost focus."
},
"prev_channel_id": {
"type": "string",
"description": "The channel ID of the previous channel, used when switching channels. Providing this ID will cause push notifications to clear on the channel being switched to."
}
}
}
}
},
"description": "Paremeters affecting how and which channels to view",
"required": true
},
"responses": {
"200": {
"description": "Channel view successful",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "Value should be \"OK\" if successful"
},
"last_viewed_at_times": {
"type": "object",
"description": "A JSON object mapping channel IDs to the channel view times"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nview := &model.ChannelView{\n ChannelId: <CHANNELID>,\n}\n// ViewChannel\npass, resp := Client.ViewChannel(<USERID>, view)\n"
}
]
}
},
"/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.\n##### Permissions\nLogged in as the user and `view_team` permission for the team. Having `manage_system` permission voids the previous requirements.\n",
"operationId": "GetChannelMembersForUser",
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "User GUID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "team_id",
"in": "path",
"description": "Team GUID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Channel members retrieval successful",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ChannelMember"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\n// GetChannelMembersForUser\nmembers, resp := Client.GetChannelMembersForUser(<USERID>, <TEAMID>, \"\")\n"
}
]
}
},
"/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.\n##### Permissions\nLogged in as the user, or have `edit_other_users` permission, and `view_team` permission for the team.\n",
"operationId": "GetChannelsForTeamForUser",
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "User GUID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "team_id",
"in": "path",
"description": "Team GUID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "include_deleted",
"in": "query",
"description": "Defines if deleted channels should be returned or not",
"schema": {
"type": "boolean",
"default": false
}
},
{
"name": "last_delete_at",
"in": "query",
"description": "Filters the deleted channels by this time in epoch format. Does not have any effect if include_deleted is set to false.",
"schema": {
"type": "integer",
"default": 0
}
}
],
"responses": {
"200": {
"description": "Channels retrieval successful",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Channel"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\n// GetChannelsForTeamForUser\nchannels, resp := Client.GetChannelsForTeamForUser(<TEAMID>, <USERID>, \"\")\n"
}
]
}
},
"/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.\n\n__Minimum server version__: 6.1\n\n##### Permissions\n\nLogged in as the user, or have `edit_other_users` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v6/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\nchannels, response, err := Client.GetChannelsForUserWithLastDeleteAt(\"fc6suoon9pbbpmhrb9c967paxe\", 0)\n"
},
{
"lang": "Curl",
"source": "curl -X GET 'http://localhost:8065/api/v4/users/fc6suoon9pbbpmhrb9c967paxe/channels' \\\n-H 'Authorization: Bearer 9kg8nqrnxprd9jbykqeg4r51hw'\n"
}
]
}
},
"/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.\n##### Permissions\nMust be logged in as user and have the `read_channel` permission, or have `edit_other_usrs` permission.\n",
"operationId": "GetChannelUnread",
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "User GUID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "channel_id",
"in": "path",
"description": "Channel GUID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Channel unreads retrieval successful",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChannelUnread"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\n// GetChannelUnread\nchannelUnread, resp := Client.GetChannelUnread(<CHANNELID>, <USERID>)\n"
}
]
}
},
"/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.\n\n##### Permissions\nMust have `manage_system` permission.\n\n__Minimum server version__: 4.10\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nchannelID := \"4xp9fdt77pncbef59f4k1qe83o\"\nschemeID := \"qjda3stwafbgpqjaxej3k76sga\"\nok, resp := UpdateChannelScheme(channelID, schemeID)\n"
},
{
"lang": "curl",
"source": "curl -X PUT \\\n https://your-mattermost-url.com/api/v4/channels/4xp9fdt77pncbef59f4k1qe83o/scheme \\\n -H 'Authorization: Bearer frn8fu5rtpyc5m4xy6q3oj4yur' \\\n -H 'Content-Type: application/json' \\\n -d '{\"scheme_id\": \"qjda3stwafbgpqjaxej3k76sga\"}'\n"
}
]
}
},
"/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.\nEach user object contains an array of group objects representing the group memberships for that user.\nEach user object contains the boolean fields `scheme_guest`, `scheme_user`, and `scheme_admin` representing the roles that user has for the given channel.\n\n##### Permissions\nMust have `manage_system` permission.\n\n__Minimum server version__: 5.14\n",
"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"
}
},
"x-code-samples": [
{
"lang": "curl",
"source": "curl -X GET \\\n 'http://your-mattermost-url.com/api/v4/channels/3wyp678obid8pggjmhmhwpah1r/members_minus_group_members?group_ids=eoezijg8zffgjmch8icy5bjd1e,ugaw6wjc3tfxpcr1eq5u5k8dhe&page=0&per_page=100' \\\n -H 'Authorization: Bearer kno8tcdotpbx3dj1gzcbx9jrqy' \\\n -H 'Content-Type: application/json' \\\n -H 'X-Requested-With: XMLHttpRequest'\n"
}
]
}
},
"/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`.\n##### Permissions\nMust have `read_channel` permission for the given channel.\n__Minimum server version__: 5.24\n",
"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"
}
},
"x-code-samples": [
{
"lang": "curl",
"source": "curl -X GET \\\n 'http://your-mattermost-url.com/api/v4/channels/3wyp678obid8pggjmhmhwpah1r/member_counts_by_group?include_timezones=true' \\\n -H 'Authorization: Bearer kno8tcdotpbx3dj1gzcbx9jrqy' \\\n -H 'Content-Type: application/json' \\\n -H 'X-Requested-With: XMLHttpRequest'\n"
}
]
}
},
"/channels/{channel_id}/moderations": {
"get": {
"tags": [
"channels"
],
"summary": "Get information about channel's moderation.",
"description": "##### Permissions\nMust have `manage_system` permission.\n\n__Minimum server version__: 5.22\n",
"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"
}
}
}
},
"/channels/{channel_id}/moderations/patch": {
"put": {
"tags": [
"channels"
],
"summary": "Update a channel's moderation settings.",
"description": "##### Permissions\nMust have `manage_system` permission.\n\n__Minimum server version__: 5.22\n",
"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"
}
}
}
},
"/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.\n__Minimum server version__: 5.26\n##### Permissions\nMust be authenticated and have the `list_team_channels` permission.\n",
"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.\n__Minimum server version__: 5.26\n##### Permissions\nMust be authenticated and have the `list_team_channels` permission.\n",
"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.\n__Minimum server version__: 5.26\n##### Permissions\nMust be authenticated and have the `list_team_channels` permission.\n",
"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"
}
}
}
},
"/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.\n__Minimum server version__: 5.26\n##### Permissions\nMust be authenticated and have the `list_team_channels` permission.\n",
"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.\n__Minimum server version__: 5.26\n##### Permissions\nMust be authenticated and have the `list_team_channels` permission.\n",
"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"
}
}
}
},
"/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.\n__Minimum server version__: 5.26\n##### Permissions\nMust be authenticated and have the `list_team_channels` permission.\n",
"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.\n__Minimum server version__: 5.26\n##### Permissions\nMust be authenticated and have the `list_team_channels` permission.\n",
"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.\n__Minimum server version__: 5.26\n##### Permissions\nMust be authenticated and have the `list_team_channels` permission.\n",
"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"
}
}
}
},
"/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`.\n##### Permissions\nMust have `create_post` permission for the channel the post is being created in.\n",
"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"
}
}
}
}
},
"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"
}
}
}
},
"/posts/ephemeral": {
"post": {
"tags": [
"posts"
],
"summary": "Create a ephemeral post",
"description": "Create a new ephemeral post in a channel.\n##### Permissions\nMust have `create_post_ephemeral` permission (currently only given to system admin)\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "client := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nclient.Login(\"email@domain.com\", \"Password1\")\n\nephemeralPost := &model.PostEphemeral{\n UserID: \"<ID OF THE USER THAT WOULD RECEIVE THE POST>\",\n Post: &model.Post{\n ChannelId: \"<ID OF CHANNEL>\",\n Message: \"<YOUR MESSAGE>\",\n },\n}\n\ncreatedPost, response := client.CreatePostEphemeral(ephemeralPost)\n"
}
]
}
},
"/posts/{post_id}": {
"get": {
"tags": [
"posts"
],
"summary": "Get a post",
"description": "Get a single post.\n##### Permissions\nMust 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.\n",
"operationId": "GetPost",
"parameters": [
{
"name": "post_id",
"in": "path",
"description": "ID of the post to get",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Post retrieval successful",
"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.\n##### Permissions\nMust be logged in as the user or have `delete_others_posts` permission.\n",
"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.\n##### Permissions\nMust have `edit_post` permission for the channel the post is in.\n",
"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"
}
}
}
},
"/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.\n##### Permissions\nMust 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.\nMust have `edit_other_users` permission if the user is not the one marking the post for himself.\n\n__Minimum server version__: 5.18\n",
"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"
}
}
}
},
"/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.\n##### Permissions\nMust have the `edit_post` permission.\n",
"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"
}
}
}
},
"/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.\n##### Permissions\nMust 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.\n",
"operationId": "GetPostThread",
"parameters": [
{
"name": "post_id",
"in": "path",
"description": "ID of a post in the thread",
"required": true,
"schema": {
"type": "string"
}
}
],
"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"
}
}
}
},
"/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.\n##### Permissions\nMust be user or have `manage_system` permission.\n",
"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"
}
}
}
},
"/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.\n##### Permissions\nMust have `read_channel` permission for the channel the post is in.\n",
"operationId": "GetFileInfosForPost",
"parameters": [
{
"name": "post_id",
"in": "path",
"description": "ID of the post",
"required": true,
"schema": {
"type": "string"
}
}
],
"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"
}
}
}
},
"/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.\nIf `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.\n##### Permissions\nMust have `read_channel` permission for the channel.\n",
"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"
}
}
],
"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"
}
}
}
},
"/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).\n##### Permissions\nMust be logged in as the user or have `edit_other_users` permission, and must have `read_channel` permission for the channel.\n__Minimum server version__: 5.14\n",
"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
}
}
],
"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"
}
}
}
},
"/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.\n##### Permissions\nMust be authenticated and have the `view_team` permission.\n",
"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"
}
}
}
},
"/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.\n##### Permissions\nMust be authenticated and have the `read_channel` permission to the channel the post is in.\n",
"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"
}
}
}
},
"/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.\n##### Permissions\nMust be authenticated and have the `read_channel` permission to the channel the post is in.\n",
"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"
}
}
}
},
"/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.\n##### Permissions\nMust be authenticated and have the `read_channel` permission to the channel the post is in.\n",
"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"
}
}
}
},
"/users/{user_id}/preferences": {
"get": {
"tags": [
"preferences"
],
"summary": "Get the user's preferences",
"description": "Get a list of the user's preferences.\n##### Permissions\nMust be logged in as the user being updated or have the `edit_other_users` permission.\n",
"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.\n##### Permissions\nMust be logged in as the user being updated or have the `edit_other_users` permission.\n",
"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"
}
}
}
}
},
"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"
}
}
}
},
"/users/{user_id}/preferences/delete": {
"post": {
"tags": [
"preferences"
],
"summary": "Delete user's preferences",
"description": "Delete a list of the user's preferences.\n##### Permissions\nMust be logged in as the user being updated or have the `edit_other_users` permission.\n",
"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"
}
}
}
}
},
"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"
}
}
}
},
"/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.\n##### Permissions\nMust be logged in as the user being updated or have the `edit_other_users` permission.\n",
"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"
}
}
}
},
"/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.\n##### Permissions\nMust be logged in as the user being updated or have the `edit_other_users` permission.\n",
"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.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Preference"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/files": {
"post": {
"tags": [
"files"
],
"summary": "Upload a file",
"description": "Uploads a file that can later be attached to a post.\n\nThis request can either be a multipart/form-data request with a channel_id, files and optional\nclient_ids defined in the FormData, or it can be a request with the channel_id and filename\ndefined as query parameters with the contents of a single file in the body of the request.\n\nOnly multipart/form-data requests are supported by server versions up to and including 4.7.\nServer versions 4.8 and higher support both types of requests.\n\n##### Permissions\nMust have `upload_file` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nfile, err := os.Open(\"file.png\")\nif err != nil {\n fmt.Fprintf(os.Stderr, \"%v\\n\", err)\n}\ndefer file.Close();\n\nbuf := bytes.NewBuffer(nil)\nio.Copy(buf, file)\ndata := buf.Bytes()\n\nchannelID := \"4xp9fdt77pncbef59f4k1qe83o\"\nfilename := \"file.png\"\n\nfileUploadResponse, response := Client.UploadFile(data, channelID, filename)\n"
},
{
"lang": "Curl",
"source": "curl -F 'files=@PATH/TO/LOCAL/FILE' \\\n-F 'channel_id=CHANNEL_ID' \\\n--header 'authorization: Bearer c49adc55z3f53ck7xtp8ebq1ir'\nhttps://your-mattermost-url.com/api/v4/files\n"
}
]
}
},
"/files/{file_id}": {
"get": {
"tags": [
"files"
],
"summary": "Get a file",
"description": "Gets a file that has been uploaded previously.\n##### Permissions\nMust have `read_channel` permission or be uploader of the file.\n",
"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": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"501": {
"$ref": "#/components/responses/NotImplemented"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nfileID := \"4xp9fdt77pncbef59f4k1qe83o\"\n\ndata, resp := Client.GetFile(fileID)\n"
}
]
}
},
"/files/{file_id}/thumbnail": {
"get": {
"tags": [
"files"
],
"summary": "Get a file's thumbnail",
"description": "Gets a file's thumbnail.\n##### Permissions\nMust have `read_channel` permission or be uploader of the file.\n",
"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": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"501": {
"$ref": "#/components/responses/NotImplemented"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nfileID := \"4xp9fdt77pncbef59f4k1qe83o\"\n\ndata, resp := Client.GetFileThumbnail(fileID)\n"
}
]
}
},
"/files/{file_id}/preview": {
"get": {
"tags": [
"files"
],
"summary": "Get a file's preview",
"description": "Gets a file's preview.\n##### Permissions\nMust have `read_channel` permission or be uploader of the file.\n",
"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": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"501": {
"$ref": "#/components/responses/NotImplemented"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nfileID := \"4xp9fdt77pncbef59f4k1qe83o\"\n\ndata, resp := Client.GetFilePreview(fileID)\n"
}
]
}
},
"/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.\n##### Permissions\nMust have `read_channel` permission or be uploader of the file.\n",
"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": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"501": {
"$ref": "#/components/responses/NotImplemented"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nfileID := \"4xp9fdt77pncbef59f4k1qe83o\"\n\ndata, resp := Client.GetFileLink(fileID)\n"
}
]
}
},
"/files/{file_id}/info": {
"get": {
"tags": [
"files"
],
"summary": "Get metadata for a file",
"description": "Gets a file's info.\n##### Permissions\nMust have `read_channel` permission or be uploader of the file.\n",
"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": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"501": {
"$ref": "#/components/responses/NotImplemented"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nfileID := \"4xp9fdt77pncbef59f4k1qe83o\"\n\ninfo, resp := Client.GetFileInfo(fileID)\n"
}
]
}
},
"/files/{file_id}/public": {
"get": {
"tags": [
"files"
],
"summary": "Get a public file",
"description": "##### Permissions\nNo permissions required.\n",
"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": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"501": {
"$ref": "#/components/responses/NotImplemented"
}
}
}
},
"/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).\n__Minimum server version__: 5.34\n##### Permissions\nMust be authenticated and have the `view_team` permission.\n",
"operationId": "SearchFiles",
"parameters": [
{
"name": "team_id",
"in": "path",
"description": "Team GUID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"required": [
"terms",
"is_or_search"
],
"properties": {
"terms": {
"type": "string",
"description": "The search terms as inputed by the user. To search for files from a user include `from:someusername`, using a user's username. To search in a specific channel include `in:somechannel`, using the channel name (not the display name). To search for specific extensions included `ext:extension`."
},
"is_or_search": {
"type": "boolean",
"description": "Set to true if an Or search should be performed vs an And search."
},
"time_zone_offset": {
"type": "integer",
"default": 0,
"description": "Offset from UTC of user timezone for date searches."
},
"include_deleted_channels": {
"type": "boolean",
"description": "Set to true if deleted channels should be included in the search. (archived channels)"
},
"page": {
"type": "integer",
"default": 0,
"description": "The page to select. (Only works with Elasticsearch)"
},
"per_page": {
"type": "integer",
"default": 60,
"description": "The number of posts per page. (Only works with Elasticsearch)"
}
}
}
}
},
"description": "The search terms and logic to use in the search.",
"required": true
},
"responses": {
"200": {
"description": "Files list retrieval successful",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileInfoList"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\nteamID := \"zWEyrTZ7GZ22aBSfoX60iWryTY\"\nfileInfoList, resp := Client.SearchFiles(teamID, \"filename\", false)\n"
},
{
"lang": "curl",
"source": "curl -X POST \\\n https://your-mattermost-url.com/api/v4/teams/zWEyrTZ7GZ22aBSfoX60iWryTY/files/search \\\n -H 'Authorization: Bearer frn8fu5rtpyc5m4xy6q3oj4yur' \\\n -H 'Content-Type: application/json' \\\n -d '{\"terms\": \"filename\", \"is_or_search\": false}'\n"
}
]
}
},
"/uploads": {
"post": {
"tags": [
"uploads"
],
"summary": "Create an upload",
"description": "Creates a new upload session.\n\n__Minimum server version__: 5.28\n##### Permissions\nMust have `upload_file` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\nus := &model.UploadSession{\n ChannelId: \"4i6jn8r483nnuqnibnmgz8jo4o\",\n Filename: \"file.png\",\n FileSize: 512000,\n}\nus, response := Client.CreateUpload(us)\n"
},
{
"lang": "Curl",
"source": "curl 'http://localhost:8065/api/v4/uploads' \\ \n-H 'Authorization: Bearer 9kg8nqrnxprd9jbykqeg4r51hw' \\\n-H 'Content-Type: application/json' \\\n--data-binary '{\"channel_id\": \"4i6jn8r483nnuqnibnmgz8jo4o\", \"filename\": \"test.png\", \"file_size\": 512000}'\n"
}
]
}
},
"/uploads/{upload_id}": {
"get": {
"tags": [
"uploads"
],
"summary": "Get an upload session",
"description": "Gets an upload session that has been previously created.\n\n##### Permissions\nMust be logged in as the user who created the upload session.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\nus, response := Client.GetUpload(\"nuyrh9ymridqmenof7exe3a6aw\")\n"
},
{
"lang": "Curl",
"source": "curl 'http://localhost:8065/api/v4/uploads/nuyrh9ymridqmenof7exe3a6aw' \\ \n-H 'Authorization: Bearer 9kg8nqrnxprd9jbykqeg4r51hw'\n"
}
]
},
"post": {
"tags": [
"uploads"
],
"summary": "Perform a file upload",
"description": "Starts or resumes a file upload. \nTo resume an existing (incomplete) upload, data should be sent starting from the offset specified in the upload session object.\n\nThe request body can be in one of two formats:\n- Binary file content streamed in request's body\n- multipart/form-data\n\n##### Permissions\nMust be logged in as the user who created the upload session.\n",
"operationId": "UploadData",
"parameters": [
{
"name": "upload_id",
"in": "path",
"description": "The ID of the upload session the data belongs to.",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object"
}
}
}
},
"responses": {
"201": {
"description": "Upload successful",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileInfo"
}
}
}
},
"204": {
"description": "Upload incomplete"
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"413": {
"$ref": "#/components/responses/TooLarge"
},
"501": {
"$ref": "#/components/responses/NotImplemented"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import (\n \"os\"\n\n \"github.com/mattermost/mattermost-server/v5/model\"\n)\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\") Client.Login(\"email@domain.com\", \"Password1\")\nfile, err := os.Open(\"file.png\") if err != nil {\n fmt.Fprintf(os.Stderr, \"%v\\n\", err)\n return\n}\ninfo, err := Client.UploadData(us, file)\n"
},
{
"lang": "Curl",
"source": "# Binary file content in request's body\ncurl -X POST 'http://localhost:8065/api/v4/uploads/qyxbzmprrjbdpdaprsxm98m6qe' \\\n-H 'Authorization: Bearer 9kg8nqrnxprd9jbykqeg4r51hw' --data-binary @file.png\n\n# multipart/form-data upload\ncurl 'http://localhost:8065/api/v4/uploads/qyxbzmprrjbdpdaprsxm98m6qe' \\\n-H 'Authorization: Bearer 9kg8nqrnxprd9jbykqeg4r51hw' -F data=@file.png\n"
}
]
}
},
"/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.\n__Minimum server version: 4.1__\n##### Permissions\nMust have `manage_jobs` permission.\n",
"operationId": "GetJobs",
"parameters": [
{
"name": "page",
"in": "query",
"description": "The page to select.",
"schema": {
"type": "integer",
"default": 0
}
},
{
"name": "per_page",
"in": "query",
"description": "The number of jobs per page.",
"schema": {
"type": "integer",
"default": 60
}
}
],
"responses": {
"200": {
"description": "Job list retrieval successful",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Job"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
},
"post": {
"tags": [
"jobs"
],
"summary": "Create a new job.",
"description": "Create a new job.\n__Minimum server version: 4.1__\n##### Permissions\nMust have `manage_jobs` permission.\n",
"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"
}
}
}
},
"/jobs/{job_id}": {
"get": {
"tags": [
"jobs"
],
"summary": "Get a job.",
"description": "Gets a single job.\n__Minimum server version: 4.1__\n##### Permissions\nMust have `manage_jobs` permission.\n",
"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"
}
}
}
},
"/jobs/{job_id}/download": {
"get": {
"tags": [
"jobs"
],
"summary": "Download the results of a job.",
"description": "Download the result of a single job.\n__Minimum server version: 5.28__\n##### Permissions\nMust have `manage_jobs` permission.\n",
"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"
}
}
}
},
"/jobs/{job_id}/cancel": {
"post": {
"tags": [
"jobs"
],
"summary": "Cancel a job.",
"description": "Cancel a job.\n__Minimum server version: 4.1__\n##### Permissions\nMust have `manage_jobs` permission.\n",
"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"
}
}
}
},
"/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.\n__Minimum server version: 4.1__\n##### Permissions\nMust have `manage_jobs` permission.\n",
"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"
}
}
}
},
"/system/timezones": {
"get": {
"tags": [
"system"
],
"summary": "Retrieve a list of supported timezones",
"description": "__Minimum server version__: 3.10\n##### Permissions\nMust be logged in.\n",
"operationId": "GetSupportedTimezone",
"responses": {
"200": {
"description": "List of timezones retrieval successful",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"500": {
"$ref": "#/components/responses/InternalServerError"
}
}
}
},
"/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.\n__Minimum server version__: 3.10\n##### Permissions\nMust be logged in.\n",
"operationId": "GetPing",
"parameters": [
{
"name": "get_server_status",
"in": "query",
"description": "Check the status of the database and file storage as well",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\n// GetPing\nstatus, resp := Client.GetPing()\n\n// Get server status with database and storage checks\nstatus, resp = Client.GetPingWithServerStatus()\n"
}
]
}
},
"/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.\n__Minimum server version__: 5.26\n##### Permissions\nMust be logged in.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nnotices, resp := Client.GetNotices(0, teamId, \"mobile-android\", \"1.2.3\", \"enUS\")\n"
}
]
}
},
"/system/notices/view": {
"put": {
"tags": [
"system"
],
"summary": "Update notices as 'viewed'",
"description": "Will mark the specified notices as 'viewed' by the logged in user.\n__Minimum server version__: 5.26\n##### Permissions\nMust be logged in.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nnotices := []string{\"id1\",\"id2\"}\nresp := Client.MarkNoticesViewed(notices)\n"
}
]
}
},
"/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.\n##### Permissions\nMust have `manage_system` permission.\n",
"operationId": "DatabaseRecycle",
"responses": {
"200": {
"description": "Database recycle successful",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StatusOK"
}
}
}
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nok, resp := Client.DatabaseRecycle()\n"
}
]
}
},
"/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.\n##### Permissions\nMust have `manage_system` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nconfig := model.Config{\n EmailSettings: model.EmailSettings{\n SMTPServer: <SMTPServer>,\n SMTPPort: <SMTPPort>,\n SMTPUsername: <SMTPUsername>,\n SMTPPassword: <SMTPPassword>,\n },\n}\n\n// TestEmail\nok, resp := Client.TestEmail(&config)\n"
}
]
}
},
"/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.\n\n##### Permissions\nMust have `manage_system` permission.\n\n__Minimum server version__: 5.16\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nsiteURL := \"https://your-new-mattermost-url.com\"\n\n// TestSiteURL\nok, resp := Client.TestSiteURL(siteUrl)\n"
}
]
}
},
"/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.\n##### Permissions\nMust have `manage_system` permission.\n__Minimum server version__: 4.8\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nconfig := model.Config{\n FileSettings: model.FileSettings{\n DriverName: model.NewString(model.IMAGE_DRIVER_S3),\n AmazonS3AccessKeyId: <AmazonS3AccessKeyId>,\n AmazonS3SecretAccessKey: <AmazonS3SecretAccessKey>,\n AmazonS3Bucket: <AmazonS3Bucket>,\n AmazonS3Endpoint: <AmazonS3Endpoint>\n },\n}\n\n// TestS3Connection\nok, resp := Client.TestS3Connection(&config)\n"
}
]
}
},
"/config": {
"get": {
"tags": [
"system"
],
"summary": "Get configuration",
"description": "Retrieve the current server configuration\n##### Permissions\nMust have `manage_system` permission.\n",
"operationId": "GetConfig",
"responses": {
"200": {
"description": "Configuration retrieval successful",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Config"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\n// GetConfig\nconfig, resp := Client.GetConfig()\n"
}
]
},
"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.\n##### Permissions\nMust have `manage_system` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\n// GetConfig\nconfig, resp := Client.GetConfig()\n\nconfig.TeamSettings.SiteName = \"MyFancyName\"\n\n// UpdateConfig\nupdatedConfig, resp := Client.UpdateConfig(config)\n"
}
]
}
},
"/config/reload": {
"post": {
"tags": [
"system"
],
"summary": "Reload configuration",
"description": "Reload the configuration file to pick up on any changes made to it.\n##### Permissions\nMust have `manage_system` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\n// ReloadConfig\nok, resp := Client.ReloadConfig()\n"
}
]
}
},
"/config/client": {
"get": {
"tags": [
"system"
],
"summary": "Get client configuration",
"description": "Get a subset of the server configuration needed by the client.\n##### Permissions\nNo permission required.\n",
"operationId": "GetClientConfig",
"parameters": [
{
"name": "format",
"in": "query",
"required": true,
"description": "Must be `old`, other formats not implemented yet",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Configuration retrieval successful"
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"501": {
"$ref": "#/components/responses/NotImplemented"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\n// GetOldClientConfig\nok, resp := Client.GetOldClientConfig()\n"
}
]
}
},
"/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\nif the corresponding config setting is set through an environment variable. Settings\nthat haven't been set through environment variables will be missing from the object.\n\n__Minimum server version__: 4.10\n\n##### Permissions\nMust have `manage_system` permission.\n",
"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"
}
}
}
},
"/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.\n##### Permissions\nMust have `manage_system` permission.\n__Minimum server version__: 5.20\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\n// GetConfig\nconfig, resp := Client.GetConfig()\n\nconfig.TeamSettings.SiteName = \"MyFancyName\"\n\n// UpdateConfig\nupdatedConfig, resp := Client.PatchConfig(config)\n"
}
]
}
},
"/config/migrate": {
"post": {
"tags": [
"system"
],
"summary": "Migrate configuration",
"description": "Migrate a file-based configuration to (or from) a database-based configuration.\nPoint the Mattermost server at the target configuration to start using it.\n\n__Minimum server version__: 5.26\n\n##### Permissions\nMust have `manage_system` permission\n",
"operationId": "MigrateConfig",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"from": {
"type": "string"
},
"to": {
"type": "string"
}
}
}
}
},
"description": "Data to be used in the migration",
"required": true
},
"responses": {
"200": {
"description": "Configuration migrated successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StatusOK"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\n// Migrate Config\nok, resp := Client.MigrateConfig(\"path/to/config.json\", \"postgres://mmuser:mostest@localhost:5432/mattermost_test?sslmode=disable&connect_timeout=10\")\n"
}
]
}
},
"/license": {
"post": {
"tags": [
"system"
],
"summary": "Upload license file",
"description": "Upload a license to enable enterprise features.\n\n__Minimum server version__: 4.0\n\n##### Permissions\nMust have `manage_system` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nfile, err := os.Open(\"<Your license file>\")\nif err != nil {\n return err\n}\ndefer file.Close()\n\ndata := &bytes.Buffer{}\nif _, err := io.Copy(data, file); err != nil {\n return err\n}\n\nok, resp := Client.UploadLicenseFile(data.Bytes())\n"
}
]
},
"delete": {
"tags": [
"system"
],
"summary": "Remove license file",
"description": "Remove the license file from the server. This will disable all enterprise features.\n\n__Minimum server version__: 4.0\n\n##### Permissions\nMust have `manage_system` permission.\n",
"operationId": "RemoveLicenseFile",
"responses": {
"200": {
"description": "License removal successful"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
}
},
"/license/client": {
"get": {
"tags": [
"system"
],
"summary": "Get client license",
"description": "Get a subset of the server license needed by the client.\n##### Permissions\nNo permission required but having the `manage_system` permission returns more information.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\n// GetOldClientLicense\nlicense, resp := Client.GetOldClientLicense()\n"
}
]
}
},
"/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\n__Minimum server version__: 5.32\n##### Permissions\nMust have `sysconsole_write_about` permission.\n",
"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"
}
}
}
},
"/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\n__Minimum server version__: 5.25\n##### Permissions\nMust have `manage_system` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\n// RequestTrialLicense\nresp := Client.RequestTrialLicense()\n"
}
]
}
},
"/trial-license/prev": {
"get": {
"tags": [
"system"
],
"summary": "Get last trial license used",
"description": "Get the last trial license used on the sevrer\n__Minimum server version__: 5.36\n##### Permissions\nMust have `manage_systems` permissions.\n",
"responses": {
"200": {
"description": "License fetched successfully."
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
}
},
"/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.\n##### Permissions\nMust have `manage_system` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\n// GetAudits\naudits, resp := Client.GetAudits(0, 100, \"\")\n"
}
]
}
},
"/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.\n##### Permissions\nMust have `manage_system` permission.\n",
"operationId": "InvalidateCaches",
"responses": {
"200": {
"description": "Caches invalidate successful",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StatusOK"
}
}
}
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\n// InvalidateCaches\nok, resp := Client.InvalidateCaches()\n"
}
]
}
},
"/logs": {
"get": {
"tags": [
"system"
],
"summary": "Get logs",
"description": "Get a page of server logs, selected with `page` and `logs_per_page` query parameters.\n##### Permissions\nMust have `manage_system` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\n// GetLogs\nlogs, resp := Client.GetLogs(0, 10)\n"
}
]
},
"post": {
"tags": [
"system"
],
"summary": "Add log message",
"description": "Add log messages to the server logs.\n##### Permissions\nUsers with `manage_system` permission can log ERROR or DEBUG messages.\nLogged in users can log ERROR or DEBUG messages when `ServiceSettings.EnableDeveloper` is `true` or just DEBUG messages when `false`.\nNon-logged in users can log ERROR or DEBUG messages when `ServiceSettings.EnableDeveloper` is `true` and cannot log when `false`.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nmessage := make(map[string]string)\nmessage[\"level\"] = \"ERROR\"\nmessage[\"message\"] = \"this is a test\"\n\n// PostLog\n_, resp := Client.PostLog(message)\n"
}
]
}
},
"/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.\n\nThe returned JSON changes based on the `name` query parameter but is always key/value pairs.\n\n__Minimum server version__: 4.0\n\n##### Permissions\nMust have `manage_system` permission.\n",
"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"
}
}
}
},
"/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.\n\n__Minimum server version__: 5.20\n\n##### Permissions\nMust have `manage_system` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nok, resp := Client.SetServerBusy(300)\n"
},
{
"lang": "curl",
"source": "curl -X POST \\\n 'http://your-mattermost-url.com/api/v4/server_busy?seconds=3600' \\\n -H 'Authorization: Bearer kno8tcdotpbx3dj1gzcbx9jrqy'\n"
}
]
},
"get": {
"tags": [
"system"
],
"summary": "Get server busy expiry time.",
"description": "Gets the timestamp corresponding to when the server busy flag will be automatically cleared.\n\n__Minimum server version__: 5.20\n\n##### Permissions\nMust have `manage_system` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\n// expires is a time.Time\nexpires, resp := Client.GetServerBusyExpires()\n"
},
{
"lang": "curl",
"source": "curl -X GET \\\n 'http://your-mattermost-url.com/api/v4/server_busy' \\\n -H 'Authorization: Bearer kno8tcdotpbx3dj1gzcbx9jrqy' \\\n -H 'Content-Type: application/json'\n"
}
]
},
"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.\n\n__Minimum server version__: 5.20\n\n##### Permissions\nMust have `manage_system` permission.\n",
"operationId": "ClearServerBusy",
"responses": {
"200": {
"description": "Server busy flag cleared successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StatusOK"
}
}
}
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nok, resp := Client.ClearServerBusy()\n"
},
{
"lang": "curl",
"source": "curl -X DELETE \\\n 'http://your-mattermost-url.com/api/v4/server_busy' \\\n -H 'Authorization: Bearer kno8tcdotpbx3dj1gzcbx9jrqy'\n"
}
]
}
},
"/notifications/ack": {
"post": {
"tags": [
"root"
],
"summary": "Acknowledge receiving of a notification",
"description": "__Minimum server version__: 3.10\n##### Permissions\nMust be logged in.\n",
"operationId": "AcknowledgeNotification",
"responses": {
"200": {
"description": "Status of the system",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PushNotification"
}
}
}
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/redirect_location": {
"get": {
"tags": [
"system"
],
"summary": "Get redirect location",
"description": "__Minimum server version__: 3.10\n##### Permissions\nMust be logged in.\n",
"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"
}
}
}
},
"/image": {
"get": {
"tags": [
"system"
],
"summary": "Get an image by url",
"description": "Fetches an image via Mattermost image proxy.\n__Minimum server version__: 3.10\n##### Permissions\nMust be logged in.\n",
"operationId": "GetImageByUrl",
"responses": {
"200": {
"description": "Image found",
"content": {
"image/*": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/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.\n__Minimum server version__: 5.27\n##### Permissions\nMust have `manage_system` permission.\n",
"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"
}
}
}
},
"/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.\n__Minimum server version__: 5.27\n##### Permissions\nMust have `manage_system` permission.\n",
"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"
}
}
}
},
"/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.\n__Minimum server version__: 5.27\n##### Permissions\nMust have `manage_system` permission.\n",
"operationId": "RestartServer",
"responses": {
"200": {
"description": "Restart started",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StatusOK"
}
}
}
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
}
},
"/warn_metrics/status": {
"get": {
"tags": [
"system"
],
"summary": "Get the warn metrics status (enabled or disabled)",
"description": "Get the status of a set of metrics (enabled or disabled) from the Systems table.\n\nThe returned JSON contains the metrics that we need to warn the admin on with regard\nto their status (we return the ones whose status is \"true\", which means that they are\nin a \"warnable\" state - e.g. a threshold has been crossed or some other condition has\nbeen fulfilled).\n\n__Minimum server version__: 5.26\n\n##### Permissions\n\nMust have `manage_system` permission.\n",
"operationId": "GetWarnMetricsStatus",
"responses": {
"200": {
"description": "Warn metrics retrieval was successful.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StatusOK"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
}
},
"/warn_metrics/ack/{warn_metric_id}": {
"post": {
"tags": [
"system"
],
"summary": "Acknowledge a warning of a metric status",
"description": "Acknowledge a warning for the warn_metric_id metric crossing a threshold (or some\nsimilar condition being fulfilled) - attempts to send an ack email to\nacknowledge@mattermost.com and sets the \"ack\" status for all the warn metrics in the system.\n\n__Minimum server version__: 5.26\n\n##### Permissions\n\nMust have `manage_system` permission.\n",
"operationId": "SendWarnMetricAck",
"parameters": [
{
"name": "warn_metric_id",
"in": "path",
"description": "Warn Metric Id.",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"description": "payload that contains the ack flag",
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"forceAck": {
"type": "boolean",
"description": "Flag which determines if the ack for the metric warning should be directly stored (without trying to send email first) or not"
}
}
}
}
}
},
"responses": {
"200": {
"description": "The acknowledgement of the warning for the metric has been successful.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StatusOK"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
}
},
"/warn_metrics/trial-license-ack/{warn_metric_id}": {
"post": {
"tags": [
"system"
],
"summary": "Request trial license and acknowledge a warning of a metric status",
"description": "Request a trial license and acknowledge a warning for the warn_metric_id metric crossing a threshold (or some\nsimilar condition being fulfilled) - sets the \"ack\" status for all the warn metrics in the system.\n\n__Minimum server version__: 5.28\n\n##### Permissions\n\nMust have `manage_system` permission.\n",
"operationId": "SendTrialLicenseWarnMetricAck",
"parameters": [
{
"name": "warn_metric_id",
"in": "path",
"description": "Warn Metric Id.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "The trial license request and the subsequent acknowledgement of the warning for the metric have been successful.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StatusOK"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
}
},
"/integrity": {
"post": {
"tags": [
"system"
],
"summary": "Perform a database integrity check",
"description": "Performs a database integrity check.\n\n\n__Note__: This check may temporarily harm system performance.\n\n\n__Minimum server version__: 5.28.0\n\n\n__Local mode only__: This endpoint is only available through [local mode](https://docs.mattermost.com/administration/mmctl-cli-tool.html#local-mode).\n",
"operationId": "CheckIntegrity",
"responses": {
"200": {
"description": "Integrity check successful",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IntegrityCheckResult"
}
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import (\n \"net\"\n \"net/http\"\n\n \"github.com/mattermost/mattermost-server/v5/model\"\n)\n\nClient := model.NewAPIv4SocketClient(socketPath)\n\nok, resp := Client.CheckIntegrity()\n"
}
]
}
},
"/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.\n__Minimum server version: 5.32__\n##### Permissions\nMust have any of the system console read permissions.\n##### License\nRequires either a E10 or E20 license.\n",
"operationId": "GenerateSupportPacket",
"responses": {
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/emoji": {
"post": {
"tags": [
"emoji"
],
"summary": "Create a custom emoji",
"description": "Create a custom emoji for the team.\n##### Permissions\nMust be authenticated.\n",
"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.\n##### Permissions\nMust be authenticated.\n",
"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 users 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"
}
}
}
},
"/emoji/{emoji_id}": {
"get": {
"tags": [
"emoji"
],
"summary": "Get a custom emoji",
"description": "Get some metadata for a custom emoji.\n##### Permissions\nMust be authenticated.\n",
"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.\n##### Permissions\nMust have the `manage_team` or `manage_system` permissions or be the user who created the emoji.\n",
"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"
}
}
}
},
"/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.\n##### Permissions\nMust be authenticated.\n\n__Minimum server version__: 4.7\n",
"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"
}
}
}
},
"/emoji/{emoji_id}/image": {
"get": {
"tags": [
"emoji"
],
"summary": "Get custom emoji image",
"description": "Get the image for a custom emoji.\n##### Permissions\nMust be authenticated.\n",
"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"
}
}
}
},
"/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.\n##### Permissions\nMust be authenticated.\n\n__Minimum server version__: 4.7\n",
"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"
}
}
}
},
"/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.\n##### Permissions\nMust be authenticated.\n\n__Minimum server version__: 4.7\n",
"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"
}
}
}
},
"/hooks/incoming": {
"post": {
"tags": [
"webhooks"
],
"summary": "Create an incoming webhook",
"description": "Create an incoming webhook for a channel.\n##### Permissions\n`manage_webhooks` for the team the webhook is in.\n\n`manage_others_incoming_webhooks` for the team the webhook is in if the user is different than the requester.\n",
"operationId": "CreateIncomingWebhook",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"channel_id"
],
"properties": {
"channel_id": {
"type": "string",
"description": "The ID of a public channel or private group that receives the webhook payloads."
},
"user_id": {
"type": "string",
"description": "The ID of the owner of the webhook if different than the requester. Required for [local mode](https://docs.mattermost.com/administration/mmctl-cli-tool.html#local-mode)."
},
"display_name": {
"type": "string",
"description": "The display name for this incoming webhook"
},
"description": {
"type": "string",
"description": "The description for this incoming webhook"
},
"username": {
"type": "string",
"description": "The username this incoming webhook will post as."
},
"icon_url": {
"type": "string",
"description": "The profile picture this incoming webhook will use when posting."
}
}
}
}
},
"description": "Incoming webhook to be created",
"required": true
},
"responses": {
"201": {
"description": "Incoming webhook creation successful",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IncomingWebhook"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
},
"get": {
"tags": [
"webhooks"
],
"summary": "List incoming webhooks",
"description": "Get a page of a list of incoming webhooks. Optionally filter for a specific team using query parameters.\n##### Permissions\n`manage_webhooks` for the system or `manage_webhooks` for the specific team.\n",
"operationId": "GetIncomingWebhooks",
"parameters": [
{
"name": "page",
"in": "query",
"description": "The page to select.",
"schema": {
"type": "integer",
"default": 0
}
},
{
"name": "per_page",
"in": "query",
"description": "The number of hooks per page.",
"schema": {
"type": "integer",
"default": 60
}
},
{
"name": "team_id",
"in": "query",
"description": "The ID of the team to get hooks for.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Incoming webhooks retrieval successful",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IncomingWebhook"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
}
},
"/hooks/incoming/{hook_id}": {
"get": {
"tags": [
"webhooks"
],
"summary": "Get an incoming webhook",
"description": "Get an incoming webhook given the hook id.\n##### Permissions\n`manage_webhooks` for system or `manage_webhooks` for the specific team or `manage_webhooks` for the channel.\n",
"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.\n##### Permissions\n`manage_webhooks` for system or `manage_webhooks` for the specific team or `manage_webhooks` for the channel.\n",
"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.\n##### Permissions\n`manage_webhooks` for system or `manage_webhooks` for the specific team or `manage_webhooks` for the channel.\n",
"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": {
"hook_id": {
"type": "string",
"description": "Incoming webhook GUID"
},
"channel_id": {
"type": "string",
"description": "The ID of a public channel or private group that receives the webhook payloads."
},
"display_name": {
"type": "string",
"description": "The display name for this incoming webhook"
},
"description": {
"type": "string",
"description": "The description for this incoming webhook"
},
"username": {
"type": "string",
"description": "The username this incoming webhook will post as."
},
"icon_url": {
"type": "string",
"description": "The profile picture this incoming webhook will use when posting."
}
}
}
}
},
"description": "Incoming webhook to be updated",
"required": true
},
"responses": {
"200": {
"description": "Webhook update successful",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IncomingWebhook"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/hooks/outgoing": {
"post": {
"tags": [
"webhooks"
],
"summary": "Create an outgoing webhook",
"description": "Create an outgoing webhook for a team.\n##### Permissions\n`manage_webhooks` for the team the webhook is in.\n\n`manage_others_outgoing_webhooks` for the team the webhook is in if the user is different than the requester.\n",
"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.\n##### Permissions\n`manage_webhooks` for the system or `manage_webhooks` for the specific team/channel.\n",
"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"
}
}
}
},
"/hooks/outgoing/{hook_id}": {
"get": {
"tags": [
"webhooks"
],
"summary": "Get an outgoing webhook",
"description": "Get an outgoing webhook given the hook id.\n##### Permissions\n`manage_webhooks` for system or `manage_webhooks` for the specific team or `manage_webhooks` for the channel.\n",
"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.\n##### Permissions\n`manage_webhooks` for system or `manage_webhooks` for the specific team or `manage_webhooks` for the channel.\n",
"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.\n##### Permissions\n`manage_webhooks` for system or `manage_webhooks` for the specific team or `manage_webhooks` for the channel.\n",
"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": {
"hook_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"
}
}
}
},
"/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.\n##### Permissions\n`manage_webhooks` for system or `manage_webhooks` for the specific team or `manage_webhooks` for the channel.\n",
"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"
}
}
}
},
"/saml/metadata": {
"get": {
"tags": [
"SAML"
],
"summary": "Get metadata",
"description": "Get SAML metadata from the server. SAML must be configured properly.\n##### Permissions\nNo permission required.\n",
"operationId": "GetSamlMetadata",
"responses": {
"200": {
"description": "SAML metadata retrieval successful",
"content": {
"application/json": {
"schema": {
"type": "string"
}
}
}
},
"501": {
"$ref": "#/components/responses/NotImplemented"
}
}
}
},
"/saml/metadatafromidp": {
"post": {
"tags": [
"SAML"
],
"summary": "Get metadata from Identity Provider",
"description": "Get SAML metadata from the Identity Provider. SAML must be configured properly.\n##### Permissions\nNo permission required.\n",
"operationId": "GetSamlMetadataFromIdp",
"responses": {
"200": {
"description": "SAML metadata retrieval successful",
"content": {
"application/json": {
"schema": {
"type": "string"
}
}
}
},
"501": {
"$ref": "#/components/responses/NotImplemented"
}
}
}
},
"/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`.\n##### Permissions\nMust have `sysconsole_write_authentication` permission.\n",
"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.\n##### Permissions\nMust have `sysconsole_write_authentication` permission.\n",
"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"
}
}
}
},
"/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`.\n##### Permissions\nMust have `sysconsole_write_authentication` permission.\n",
"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.\n##### Permissions\nMust have `sysconsole_write_authentication` permission.\n",
"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"
}
}
}
},
"/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`.\n##### Permissions\nMust have `sysconsole_write_authentication` permission.\n",
"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.\n##### Permissions\nMust have `sysconsole_write_authentication` permission.\n",
"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"
}
}
}
},
"/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.\n##### Permissions\nMust have `sysconsole_write_authentication` permission.\n",
"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"
}
}
}
},
"/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.\n__Minimum server version__: 5.35\n##### Permissions\nMust have `manage_system` permission.\n",
"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": null,
"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"
}
}
}
},
"/compliance/reports": {
"post": {
"tags": [
"compliance"
],
"summary": "Create report",
"description": "Create and save a compliance report.\n##### Permissions\nMust have `manage_system` permission.\n",
"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.\n##### Permissions\nMust have `manage_system` permission.\n",
"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"
}
}
}
},
"/compliance/reports/{report_id}": {
"get": {
"tags": [
"compliance"
],
"summary": "Get a report",
"description": "Get a compliance reports previously created.\n##### Permissions\nMust have `manage_system` permission.\n",
"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"
}
}
}
},
"/compliance/reports/{report_id}/download": {
"get": {
"tags": [
"compliance"
],
"summary": "Download a report",
"description": "Download the full contents of a report as a file.\n##### Permissions\nMust have `manage_system` permission.\n",
"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"
}
}
}
},
"/ldap/sync": {
"post": {
"tags": [
"LDAP"
],
"summary": "Sync with LDAP",
"description": "Synchronize any user attribute changes in the configured AD/LDAP server with Mattermost.\n##### Permissions\nMust have `manage_system` permission.\n",
"operationId": "SyncLdap",
"responses": {
"200": {
"description": "LDAP sync successful",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StatusOK"
}
}
}
},
"501": {
"$ref": "#/components/responses/NotImplemented"
}
}
}
},
"/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.\n##### Permissions\nMust have `manage_system` permission.\n",
"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"
}
}
}
},
"/ldap/groups": {
"get": {
"tags": [
"ldap"
],
"summary": "Returns a list of LDAP groups",
"description": "##### Permissions\nMust have `manage_system` permission.\n__Minimum server version__: 5.11\n",
"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. There is a maximum limit of 200 users per page.",
"schema": {
"type": "integer",
"default": 60
}
}
],
"responses": {
"200": {
"description": "LDAP group page retrieval successful",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/LDAPGroupsPaged"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
}
}
},
"/ldap/groups/{remote_id}/link": {
"post": {
"tags": [
"ldap"
],
"summary": "Link a LDAP group",
"description": "##### Permissions\nMust have `manage_system` permission.\n__Minimum server version__: 5.11\n",
"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\nMust have `manage_system` permission.\n__Minimum server version__: 5.11\n",
"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"
}
}
}
},
"/ldap/migrateid": {
"post": {
"tags": [
"LDAP"
],
"summary": "Migrate Id LDAP",
"description": "Migrate LDAP IdAttribute to new value.\n##### Permissions\nMust have `manage_system` permission.\n__Minimum server version__: 5.26\n",
"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"
}
}
}
},
"/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`.\n##### Permissions\nMust have `manage_system` permission.\n",
"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.\n##### Permissions\nMust have `manage_system` permission.\n",
"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"
}
}
}
},
"/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`.\n##### Permissions\nMust have `manage_system` permission.\n",
"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.\n##### Permissions\nMust have `manage_system` permission.\n",
"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"
}
}
}
},
"/groups": {
"get": {
"tags": [
"groups"
],
"summary": "Get groups",
"description": "Retrieve a list of all groups not associated to a particular channel or team.\n\n`not_associated_to_team` **OR** `not_associated_to_channel` is required.\n\nIf you use `not_associated_to_team`, you must be a team admin for that particular team (permission to manage that team).\n\nIf you use `not_associated_to_channel`, you must be a channel admin for that particular channel (permission to manage that channel).\n\n__Minimum server version__: 5.11\n",
"operationId": "GetGroups",
"parameters": [
{
"name": "page",
"in": "query",
"description": "The page to select.",
"schema": {
"type": "integer",
"default": 0
}
},
{
"name": "per_page",
"in": "query",
"description": "The number of groups per page.",
"schema": {
"type": "integer",
"default": 60
}
},
{
"name": "q",
"in": "query",
"description": "String to pattern match the `name` and `display_name` field. Will return all groups whose `name` and `display_name` field match any of the text.",
"schema": {
"type": "string"
}
},
{
"name": "include_member_count",
"in": "query",
"description": "Boolean which adds the `member_count` attribute to each group JSON object",
"schema": {
"type": "boolean"
}
},
{
"name": "not_associated_to_team",
"in": "query",
"description": "Team GUID which is used to return all the groups not associated to this team",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "not_associated_to_channel",
"in": "query",
"description": "Group GUID which is used to return all the groups not associated to this channel",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "since",
"in": "query",
"description": "Only return groups that have been modified since the given Unix timestamp (in milliseconds). All modified groups, including deleted and created groups, will be returned.\n__Minimum server version__: 5.24\n",
"schema": {
"type": "integer"
}
}
],
"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"
}
}
}
},
"/groups/{group_id}": {
"get": {
"tags": [
"groups"
],
"summary": "Get a group",
"description": "Get group from the provided group id string\n\n##### Permissions\nMust have `manage_system` permission.\n\n__Minimum server version__: 5.11\n",
"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"
}
}
}
},
"/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.\n\n##### Permissions\nMust have `manage_system` permission.\n\n__Minimum server version__: 5.11\n",
"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"
}
}
}
},
"/groups/{group_id}/teams/{team_id}/link": {
"post": {
"tags": [
"groups"
],
"summary": "Link a team to a group",
"description": "Link a team to a group\n##### Permissions\nMust have `manage_team` permission.\n\n__Minimum server version__: 5.11\n",
"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\n##### Permissions\nMust have `manage_team` permission.\n\n__Minimum server version__: 5.11\n",
"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"
}
}
}
},
"/groups/{group_id}/channels/{channel_id}/link": {
"post": {
"tags": [
"groups"
],
"summary": "Link a channel to a group",
"description": "Link a channel to a group\n##### Permissions\nIf the channel is private, you must have `manage_private_channel_members` permission.\nOtherwise, you must have the `manage_public_channel_members` permission.\n\n__Minimum server version__: 5.11\n",
"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\n##### Permissions\nIf the channel is private, you must have `manage_private_channel_members` permission.\nOtherwise, you must have the `manage_public_channel_members` permission.\n\n__Minimum server version__: 5.11\n",
"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"
}
}
}
},
"/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\n##### Permissions\nMust have `manage_system` permission.\n\n__Minimum server version__: 5.11\n",
"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"
}
}
}
},
"/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\n##### Permissions\nMust have `manage_system` permission.\n\n__Minimum server version__: 5.11\n",
"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"
}
}
}
},
"/groups/{group_id}/teams": {
"get": {
"tags": [
"groups"
],
"summary": "Get group teams",
"description": "Retrieve the list of teams associated to the group\n##### Permissions\nMust have `manage_system` permission.\n\n__Minimum server version__: 5.11\n",
"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"
}
}
}
},
"/groups/{group_id}/channels": {
"get": {
"tags": [
"groups"
],
"summary": "Get group channels",
"description": "Retrieve the list of channels associated to the group\n##### Permissions\nMust have `manage_system` permission.\n\n__Minimum server version__: 5.11\n",
"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"
}
}
}
},
"/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.\n\n##### Permissions\nMust have `manage_system` permission.\n\n__Minimum server version__: 5.11\n",
"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"
}
}
}
},
"/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.\n\n##### Permissions\nMust have `manage_system` permission.\n\n__Minimum server version__: 5.11\n",
"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"
}
}
}
},
"/groups/{group_id}/members": {
"get": {
"tags": [
"groups"
],
"summary": "Get group users",
"description": "Retrieve the list of users associated with a given group.\n\n##### Permissions\nMust have `manage_system` permission.\n\n__Minimum server version__: 5.11\n",
"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"
}
}
}
},
"/groups/{group_id}/stats": {
"get": {
"tags": [
"groups"
],
"summary": "Get group stats",
"description": "Retrieve the stats of a given group.\n\n##### Permissions\nMust have `manage_system` permission.\n\n__Minimum server version__: 5.26\n",
"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"
}
}
}
},
"/channels/{channel_id}/groups": {
"get": {
"tags": [
"groups"
],
"summary": "Get channel groups",
"description": "Retrieve the list of groups associated with a given channel.\n\n##### Permissions\nMust have `manage_system` permission.\n\n__Minimum server version__: 5.11\n",
"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"
}
}
}
},
"/teams/{team_id}/groups": {
"get": {
"tags": [
"groups"
],
"summary": "Get team groups",
"description": "Retrieve the list of groups associated with a given team.\n\n__Minimum server version__: 5.11\n",
"operationId": "GetGroupsByTeam",
"parameters": [
{
"name": "team_id",
"in": "path",
"description": "Team GUID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "page",
"in": "query",
"description": "The page to select.",
"schema": {
"type": "integer",
"default": 0
}
},
{
"name": "per_page",
"in": "query",
"description": "The number of groups per page.",
"schema": {
"type": "integer",
"default": 60
}
},
{
"name": "filter_allow_reference",
"in": "query",
"description": "Boolean which filters in the group entries with the `allow_reference` attribute set.",
"schema": {
"type": "boolean",
"default": false
}
}
],
"responses": {
"200": {
"description": "Group list retrieval successful",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Group"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
},
"501": {
"$ref": "#/components/responses/NotImplemented"
}
}
}
},
"/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.\n\n##### Permissions\nMust have `manage_system` permission or can access only for current user\n\n__Minimum server version__: 5.11\n",
"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
}
}
],
"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"
}
}
}
},
"/users/{user_id}/groups": {
"get": {
"tags": [
"groups"
],
"summary": "Get groups for a userId",
"description": "Retrieve the list of groups associated to the user\n\n__Minimum server version__: 5.24\n",
"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"
}
}
}
},
"/cluster/status": {
"get": {
"tags": [
"cluster"
],
"summary": "Get cluster status",
"description": "Get a set of information for each node in the cluster, useful for checking the status and health of each node.\n##### Permissions\nMust have `manage_system` permission.\n",
"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"
}
}
}
},
"/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.\n##### Permissions\nNo permission required.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\n// GetBrandImage\nimg, err := Client.GetBrandImage()\n"
}
]
},
"post": {
"tags": [
"brand"
],
"summary": "Upload brand image",
"description": "Uploads a brand image.\n##### Permissions\nMust have `manage_system` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nfile, err := os.Open(\"<Your image>\")\nif err != nil {\n return err\n}\ndefer file.Close()\n\ndata := &bytes.Buffer{}\nif _, err := io.Copy(data, file); err != nil {\n return err\n}\n\nok, resp := Client.UploadBrandImage(data.Bytes())\n"
}
]
},
"delete": {
"tags": [
"brand"
],
"summary": "Delete current brand image",
"description": "Deletes the previously uploaded brand image. Returns 404 if no brand image has been uploaded.\n##### Permissions\nMust have `manage_system` permission.\n__Minimum server version: 5.6__\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\n// Delete brand image\nresp := Client.DeleteBrandImage()\n"
}
]
}
},
"/commands": {
"post": {
"tags": [
"commands"
],
"summary": "Create a command",
"description": "Create a command for a team.\n##### Permissions\n`manage_slash_commands` for the team the command is in.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nnewCmd := &model.Command {\n TeamId: <TEAMID>,\n URL: \"http://nowhere.com\",\n Method: model.COMMAND_METHOD_POST,\n Trigger: \"trigger\",\n AutoComplete: false,\n Description: \"Description\",\n DisplayName: \"Display name\",\n IconURL: \"IconURL\",\n Username: \"Username\"\n}\n\n// CreateCommand\ncreatedCmd, resp := Client.CreateCommand(newCmd)\n"
}
]
},
"get": {
"tags": [
"commands"
],
"summary": "List commands for a team",
"description": "List commands for a team.\n##### Permissions\n`manage_slash_commands` if need list custom commands.\n",
"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\nif the user have access plus the system commands, otherwise just the system commands.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\n// ListCommands\n// The second parameter is to set if you want only custom commands (true) or defaults commands (false)\nlistCommands, resp := Client.ListCommands(<TEAMID>, true)\n"
}
]
}
},
"/teams/{team_id}/commands/autocomplete": {
"get": {
"tags": [
"commands"
],
"summary": "List autocomplete commands",
"description": "List autocomplete commands in the team.\n##### Permissions\n`view_team` for the team.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\n// ListAutocompleteCommands\nlistCommands, resp := Client.ListAutocompleteCommands(<TEAMID>)\n"
}
]
}
},
"/teams/{team_id}/commands/autocomplete_suggestions": {
"get": {
"tags": [
"commands"
],
"summary": "List commands' autocomplete data",
"description": "List commands' autocomplete data for the team.\n##### Permissions\n`view_team` for the team.\n__Minimum server version__: 5.24\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\n// ListCommandAutocompleteSuggestions\nteamID := \"4xp9fdt77pncbef59f4k1qe83o\"\nuserInput := \"/jira\"\nlistCommands, resp := Client.ListCommandAutocompleteSuggestions(userInput, teamID)\n"
}
]
}
},
"/commands/{command_id}": {
"get": {
"tags": [
"commands"
],
"summary": "Get a command",
"description": "Get a command definition based on command id string.\n##### Permissions\nMust have `manage_slash_commands` permission for the team the command is in.\n\n__Minimum server version__: 5.22\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\n// GetCommand\ncmd, resp := Client.GetCommand(<COMMANDID>)\n"
}
]
},
"put": {
"tags": [
"commands"
],
"summary": "Update a command",
"description": "Update a single command based on command id string and Command struct.\n##### Permissions\nMust have `manage_slash_commands` permission for the team the command is in.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\ncmdToUpdate := &model.Command{\n CreatorId: <USERID>,\n TeamId: <TEAMID>,\n URL: \"<http://nowhere.com/change>\",\n Trigger: <NEWTRIGGERNAME>,\n Id: <COMMANDID>,\n}\n\n// UpdateCommand\nlistCommands, resp := Client.UpdateCommand(cmdToUpdate)\n"
}
]
},
"delete": {
"tags": [
"commands"
],
"summary": "Delete a command",
"description": "Delete a command based on command id string.\n##### Permissions\nMust have `manage_slash_commands` permission for the team the command is in.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\n// DeleteCommand\nok, resp := Client.DeleteCommand(<COMMANDID>)\n"
}
]
}
},
"/commands/{command_id}/move": {
"put": {
"tags": [
"commands"
],
"summary": "Move a command",
"description": "Move a command to a different team based on command id string.\n##### Permissions\nMust have `manage_slash_commands` permission for the team the command is currently in and the destination team.\n\n__Minimum server version__: 5.22\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\n// MoveCommand\nok, resp := Client.MoveCommand(<TEAMID>,<COMMANDID>)\n"
}
]
}
},
"/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.\n##### Permissions\nMust have `manage_slash_commands` permission for the team the command is in.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\n// RegenCommandToken\nnewToken, resp := Client.RegenCommandToken(<COMMANDID>)\n"
}
]
}
},
"/commands/execute": {
"post": {
"tags": [
"commands"
],
"summary": "Execute a command",
"description": "Execute a command on a team.\n##### Permissions\nMust have `use_slash_commands` permission for the team the command is in.\n",
"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"
}
}
}
}
},
"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"
}
}
}
},
"/oauth/apps": {
"post": {
"tags": [
"OAuth"
],
"summary": "Register OAuth app",
"description": "Register an OAuth 2.0 client application with Mattermost as the service provider.\n##### Permissions\nMust have `manage_oauth` permission.\n",
"operationId": "CreateOAuthApp",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"name",
"description",
"callback_urls",
"homepage"
],
"properties": {
"name": {
"type": "string",
"description": "The name of the client application"
},
"description": {
"type": "string",
"description": "A short description of the application"
},
"icon_url": {
"type": "string",
"description": "A URL to an icon to display with the application"
},
"callback_urls": {
"type": "array",
"items": {
"type": "string"
},
"description": "A list of callback URLs for the appliation"
},
"homepage": {
"type": "string",
"description": "A link to the website of the application"
},
"is_trusted": {
"type": "boolean",
"description": "Set this to `true` to skip asking users for permission"
}
}
}
}
},
"description": "OAuth application to register",
"required": true
},
"responses": {
"201": {
"description": "App registration successful",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OAuthApp"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"501": {
"$ref": "#/components/responses/NotImplemented"
}
}
},
"get": {
"tags": [
"OAuth"
],
"summary": "Get OAuth apps",
"description": "Get a page of OAuth 2.0 client applications registered with Mattermost.\n##### Permissions\nWith `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.\n",
"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"
}
}
}
},
"/oauth/apps/{app_id}": {
"get": {
"tags": [
"OAuth"
],
"summary": "Get an OAuth app",
"description": "Get an OAuth 2.0 client application registered with Mattermost.\n##### Permissions\nIf app creator, must have `mange_oauth` permission otherwise `manage_system_wide_oauth` permission is required.\n",
"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.\n##### Permissions\nIf app creator, must have `mange_oauth` permission otherwise `manage_system_wide_oauth` permission is required.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nappToUpdate := &model.OAuthApp{\n Id: <APP ID>,\n Name: <APP NAME>,\n Description: <APP DESCRIPTION>,\n IconURL: <URL TO APP ICON>,\n CallbackUrls: [<CALLBACK URL1>, <CALLBACK URL2>],\n Homepage: <URL TO APP HOMEPAGE>,\n IsTrusted: <BOOLEAN>\n}\n\n// UpdateOAuthApp\nupdatedApp, resp := Client.UpdateOAuthApp(appToUpdate)\n"
}
]
},
"delete": {
"tags": [
"OAuth"
],
"summary": "Delete an OAuth app",
"description": "Delete and unregister an OAuth 2.0 client application \n##### Permissions\nIf app creator, must have `mange_oauth` permission otherwise `manage_system_wide_oauth` permission is required.\n",
"operationId": "DeleteOAuthApp",
"parameters": [
{
"name": "app_id",
"in": "path",
"description": "Application client id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "App deletion successful",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StatusOK"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"501": {
"$ref": "#/components/responses/NotImplemented"
}
}
}
},
"/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.\n##### Permissions\nIf app creator, must have `mange_oauth` permission otherwise `manage_system_wide_oauth` permission is required.\n",
"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"
}
}
}
},
"/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.\n##### Permissions\nMust be authenticated.\n",
"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"
}
}
}
},
"/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.\n##### Permissions\nMust be authenticated as the user or have `edit_other_users` permission.\n",
"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"
}
}
}
},
"/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.\nOptionally provide a configuration in the request body to test. If no valid configuration is present in the\nrequest body the current server configuration will be tested.\n\n__Minimum server version__: 4.1\n##### Permissions\nMust have `manage_system` permission.\n",
"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"
}
}
}
},
"/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\nnecessary to schedule a new Elasticsearch indexing job to repopulate the indexes.\n__Minimum server version__: 4.1\n##### Permissions\nMust have `manage_system` permission.\n",
"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"
}
}
}
},
"/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\nnecessary to schedule a new Bleve indexing job to repopulate the indexes.\n__Minimum server version__: 5.24\n##### Permissions\nMust have `sysconsole_write_experimental` permission.\n",
"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"
}
}
}
},
"/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,\nincluding what data should be purged and the cutoff times for each data\ntype that should be purged.\n\n__Minimum server version__: 4.3\n\n##### Permissions\nRequires an active session but no other permissions.\n\n##### License\nRequires an E20 license.\n",
"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"
}
}
}
},
"/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\npolicies from the server.\n\n__Minimum server version__: 5.35\n\n##### Permissions\nMust have the `sysconsole_read_compliance_data_retention` permission.\n\n##### License\nRequires an E20 license.\n",
"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"
}
}
}
},
"/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\npolicies from the server.\n\n__Minimum server version__: 5.35\n\n##### Permissions\nMust have the `sysconsole_read_compliance_data_retention` permission.\n\n##### License\nRequires an E20 license.\n",
"operationId": "GetDataRetentionPolicies",
"parameters": [
{
"name": "page",
"in": "query",
"description": "The page to select.",
"schema": {
"type": "integer",
"default": 0
}
},
{
"name": "per_page",
"in": "query",
"description": "The number of policies per page. There is a maximum limit of 200 per page.",
"schema": {
"type": "integer",
"default": 60
}
}
],
"responses": {
"200": {
"description": "Retention policies' details retrieved successfully.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DataRetentionPolicyWithTeamAndChannelCounts"
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
},
"501": {
"$ref": "#/components/responses/NotImplemented"
}
}
},
"post": {
"tags": [
"data retention"
],
"summary": "Create a new granular data retention policy",
"description": "Creates a new granular data retention policy with the specified display\nname and post duration.\n\n__Minimum server version__: 5.35\n\n##### Permissions\nMust have the `sysconsole_write_compliance_data_retention` permission.\n\n##### License\nRequires an E20 license.\n",
"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"
}
}
}
},
"/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.\n\n__Minimum server version__: 5.35\n\n##### Permissions\nMust have the `sysconsole_read_compliance_data_retention` permission.\n\n##### License\nRequires an E20 license.\n",
"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.\nIf any fields are omitted, they will not be changed.\n\n__Minimum server version__: 5.35\n\n##### Permissions\nMust have the `sysconsole_write_compliance_data_retention` permission.\n\n##### License\nRequires an E20 license.\n",
"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.\n\n__Minimum server version__: 5.35\n\n##### Permissions\nMust have the `sysconsole_write_compliance_data_retention` permission.\n\n##### License\nRequires an E20 license.\n",
"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"
}
}
}
},
"/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.\n\n__Minimum server version__: 5.35\n\n##### Permissions\nMust have the `sysconsole_read_compliance_data_retention` permission.\n\n##### License\nRequires an E20 license.\n",
"operationId": "GetTeamsForRetentionPolicy",
"parameters": [
{
"name": "policy_id",
"in": "path",
"description": "The ID of the granular retention policy.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "page",
"in": "query",
"description": "The page to select.",
"schema": {
"type": "integer",
"default": 0
}
},
{
"name": "per_page",
"in": "query",
"description": "The number of teams per page. There is a maximum limit of 200 per page.",
"schema": {
"type": "integer",
"default": 60
}
}
],
"responses": {
"200": {
"description": "Teams for retention policy successfully retrieved.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Team"
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
},
"501": {
"$ref": "#/components/responses/NotImplemented"
}
}
},
"post": {
"tags": [
"data retention"
],
"summary": "Add teams to a granular data retention policy",
"description": "Adds teams to a granular data retention policy.\n\n __Minimum server version__: 5.35\n\n##### Permissions\nMust have the `sysconsole_write_compliance_data_retention` permission.\n\n##### License\nRequires an E20 license.\n",
"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.\n\n __Minimum server version__: 5.35\n\n##### Permissions\nMust have the `sysconsole_write_compliance_data_retention` permission.\n\n##### License\nRequires an E20 license.\n",
"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"
}
}
}
},
"/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.\n\n__Minimum server version__: 5.35\n\n##### Permissions\nMust have the `sysconsole_read_compliance_data_retention` permission.\n\n##### License\nRequires an E20 license.\n",
"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"
}
}
}
},
"/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.\n\n__Minimum server version__: 5.35\n\n##### Permissions\nMust have the `sysconsole_read_compliance_data_retention` permission.\n\n##### License\nRequires an E20 license.\n",
"operationId": "GetChannelsForRetentionPolicy",
"parameters": [
{
"name": "policy_id",
"in": "path",
"description": "The ID of the granular retention policy.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "page",
"in": "query",
"description": "The page to select.",
"schema": {
"type": "integer",
"default": 0
}
},
{
"name": "per_page",
"in": "query",
"description": "The number of channels per page. There is a maximum limit of 200 per page.",
"schema": {
"type": "integer",
"default": 60
}
}
],
"responses": {
"200": {
"description": "Channels for retention policy successfully retrieved.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChannelListWithTeamData"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
},
"501": {
"$ref": "#/components/responses/NotImplemented"
}
}
},
"post": {
"tags": [
"data retention"
],
"summary": "Add channels to a granular data retention policy",
"description": "Adds channels to a granular data retention policy.\n\n __Minimum server version__: 5.35\n\n##### Permissions\nMust have the `sysconsole_write_compliance_data_retention` permission.\n\n##### License\nRequires an E20 license.\n",
"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.\n\n __Minimum server version__: 5.35\n\n##### Permissions\nMust have the `sysconsole_write_compliance_data_retention` permission.\n\n##### License\nRequires an E20 license.\n",
"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"
}
}
}
},
"/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.\n\n__Minimum server version__: 5.35\n\n##### Permissions\nMust have the `sysconsole_read_compliance_data_retention` permission.\n\n##### License\nRequires an E20 license.\n",
"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",
"description": "Filters results to channels belonging to the given team ids\n"
},
"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\n"
},
"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\n"
},
"deleted": {
"type": "boolean",
"description": "Filters results to only return deleted / archived channels\n"
}
}
}
}
}
},
"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"
}
}
}
},
"/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.\n\n##### Permissions\nMust have `manage_system` permission.\n\n__Minimum server version__: 4.4\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import (\n \"bytes\"\n \"io/ioutil\"\n \"log\"\n\n \"github.com/mattermost/mattermost-server/v5/model\"\n)\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\ntarData, err := ioutil.ReadFile(\"plugin.tar.gz\")\nif err != nil {\n log.Fatal(\"error while reading file\")\n}\n\n// Not forced\nmanifest, resp := Client.UploadPlugin(bytes.NewReader(tarData))\n\n// Forced\nmanifest, resp := Client.UploadPluginForced(bytes.NewReader(tarData))\n"
}
]
},
"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.\n\n##### Permissions\nMust have `manage_system` permission.\n\n__Minimum server version__: 4.4\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\npluginsResp, resp := Client.GetPlugins()\n"
}
]
}
},
"/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.\n\n##### Permissions\nMust have `manage_system` permission.\n\n__Minimum server version__: 5.14\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import (\n \"github.com/mattermost/mattermost-server/v5/model\"\n)\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nurl := \"https://mysite.com/my-plugin.tar.gz\"\n\n// Not forced\nmanifest, resp := Client.InstallPluginFromUrl(url, false)\n\n// Forced\nmanifest, resp := Client.InstallPluginFromUrl(url, true)\n"
}
]
}
},
"/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.\n\n##### Permissions\nMust have `manage_system` permission.\n\n__Minimum server version__: 4.4\n",
"operationId": "RemovePlugin",
"parameters": [
{
"name": "plugin_id",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\npluginID := \"com.mattermost.demo-plugin\"\n\nok, resp = Client.RemovePlugin(pluginID)\n"
}
]
}
},
"/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.\n\n##### Permissions\nMust have `manage_system` permission.\n\n__Minimum server version__: 4.4\n",
"operationId": "EnablePlugin",
"parameters": [
{
"name": "plugin_id",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\npluginID := \"com.mattermost.demo-plugin\"\n\nok, resp = Client.EnablePlugin(pluginID)\n"
}
]
}
},
"/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.\n\n##### Permissions\nMust have `manage_system` permission.\n\n__Minimum server version__: 4.4\n",
"operationId": "DisablePlugin",
"parameters": [
{
"name": "plugin_id",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\npluginID := \"com.mattermost.demo-plugin\"\n\nok, resp = Client.DisablePlugin(pluginID)\n"
}
]
}
},
"/plugins/webapp": {
"get": {
"tags": [
"plugins"
],
"summary": "Get webapp plugins",
"description": "Get a list of web app plugins installed and activated on the server.\n\n##### Permissions\nNo permissions required.\n\n__Minimum server version__: 4.4\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\n\nmanifests, resp := Client.GetWebappPlugins()\n"
}
]
}
},
"/plugins/statuses": {
"get": {
"tags": [
"plugins"
],
"summary": "Get plugins status",
"description": "Returns the status for plugins installed anywhere in the cluster\n\n##### Permissions\nNo permissions required.\n\n__Minimum server version__: 4.4\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\n\nmanifests, resp := Client.GetPluginStatuses()\n"
}
]
}
},
"/plugins/marketplace": {
"post": {
"tags": [
"plugins"
],
"summary": "Installs a marketplace plugin",
"description": "Installs a plugin listed in the marketplace server.\n\n##### Permissions\nMust have `manage_system` permission.\n\n__Minimum server version__: 5.16\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nplugin := &model.InstallMarketplacePluginRequest{\n Id: \"antivirus\",\n Version: \"0.1.2\",\n}\n\nok, resp = Client.InstallMarketplacePlugin(plugin)\n"
}
]
},
"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.\n\n##### Permissions\nMust have `manage_system` permission.\n\n__Minimum server version__: 5.16\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nfilter := &model.MarketplacePluginFilter{\n Page: 1,\n PerPage: 10,\n Filter: \"antivirus\",\n ServerVersion: \"0.1.2\",\n LocalOnly: true,\n}\n\nok, resp = Client.GetMarketplacePlugins(filter)\n"
}
]
}
},
"/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.\n__Minimum server version: 5.33__\n##### Permissions\nMust have `manage_system` permissions.\n",
"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.\n__Minimum server version: 5.33__\n##### Permissions\nMust have `manage_system` permissions.\n",
"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"
}
}
}
},
"/roles": {
"get": {
"tags": [
"roles"
],
"summary": "Get a list of all the roles",
"description": "##### Permissions\n\n`manage_system` permission is required.\n\n__Minimum server version__: 5.33\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nroles, resp := Client.GetAllRoles()\n"
}
]
}
},
"/roles/{role_id}": {
"get": {
"tags": [
"roles"
],
"summary": "Get a role",
"description": "Get a role from the provided role id.\n\n##### Permissions\nRequires an active session but no other permissions.\n\n__Minimum server version__: 4.9\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nrole, resp := Client.GetRole(<ROLEID>, \"\")\n"
}
]
}
},
"/roles/name/{role_name}": {
"get": {
"tags": [
"roles"
],
"summary": "Get a role",
"description": "Get a role from the provided role name.\n\n##### Permissions\nRequires an active session but no other permissions.\n\n__Minimum server version__: 4.9\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nrole, resp := Client.GetRoleByName(<ROLENAME>, \"\")\n"
}
]
}
},
"/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.\n\n##### Permissions\n`manage_system` permission is required.\n\n__Minimum server version__: 4.9\n",
"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"
}
}
}
},
"/roles/names": {
"post": {
"tags": [
"roles"
],
"summary": "Get a list of roles by name",
"description": "Get a list of roles from their names.\n\n##### Permissions\nRequires an active session but no other permissions.\n\n__Minimum server version__: 4.9\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nroleNames := []string{<NAME OF ROLE1>, <NAME OF ROLE2>, ...}\n\nroles, resp := Client.GetRolesByNames(roleNames)\n"
}
]
}
},
"/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.\n\n##### Permissions\nMust have `manage_system` permission.\n\n__Minimum server version__: 5.0\n",
"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.\n\n##### Permissions\nMust have `manage_system` permission.\n\n__Minimum server version__: 5.0\n",
"operationId": "CreateScheme",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"name",
"scope"
],
"properties": {
"name": {
"type": "string",
"description": "The name of the scheme"
},
"description": {
"type": "string",
"description": "The description of the scheme"
},
"scope": {
"type": "string",
"description": "The scope of the scheme (\"team\" or \"channel\")"
}
}
}
}
},
"description": "Scheme object to create",
"required": true
},
"responses": {
"201": {
"description": "Scheme creation successful",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Scheme"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"501": {
"$ref": "#/components/responses/NotImplemented"
}
}
}
},
"/schemes/{scheme_id}": {
"get": {
"tags": [
"schemes"
],
"summary": "Get a scheme",
"description": "Get a scheme from the provided scheme id.\n\n##### Permissions\nMust have `manage_system` permission.\n\n__Minimum server version__: 5.0\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nscheme, resp := Client.GetScheme(<SCHEMEID>, \"\")\n"
}
]
},
"delete": {
"tags": [
"schemes"
],
"summary": "Delete a scheme",
"description": "Soft deletes a scheme, by marking the scheme as deleted in the database.\n\n##### Permissions\nMust have `manage_system` permission.\n\n__Minimum server version__: 5.0\n",
"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"
}
}
}
},
"/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.\n\n##### Permissions\n`manage_system` permission is required.\n\n__Minimum server version__: 5.0\n",
"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"
}
}
}
},
"/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.\nUse the query parameters to modify the behaviour of this endpoint.\n\n##### Permissions\n`manage_system` permission is required.\n\n__Minimum server version__: 5.0\n",
"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"
}
}
}
},
"/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.\nUse the query parameters to modify the behaviour of this endpoint.\n\n##### Permissions\n`manage_system` permission is required.\n\n__Minimum server version__: 5.0\n",
"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"
}
}
}
},
"/terms_of_service": {
"get": {
"tags": [
"terms of service"
],
"summary": "Get latest terms of service",
"description": "Get latest terms of service from the server\n\n__Minimum server version__: 5.4\n##### Permissions\nMust be authenticated.\n",
"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\n\n__Minimum server version__: 5.4\n##### Permissions\nMust have `manage_system` permission.\n",
"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"
}
}
}
},
"/sharedchannels/{team_id}": {
"get": {
"tags": [
"shared channels"
],
"summary": "Get all shared channels for team.",
"description": "Get all shared channels for a team.\n\n__Minimum server version__: 5.50\n\n##### Permissions\nMust be authenticated.\n",
"operationId": "GetAllSharedChannels",
"parameters": [
{
"name": "team_id",
"in": "path",
"description": "Team Id",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "page",
"in": "query",
"schema": {
"type": "integer",
"default": 0
}
},
{
"name": "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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nteamID := \"4xp9fdt77pncbef59f4k1qe83o\"\n\nshared_channels, err := Client.GetAllSharedChannels(teamID, 0, 100)\n"
},
{
"lang": "curl",
"source": "curl -X POST \\\n 'http://your-mattermost-url.com/api/v4/sharedchannels/4xp9fdt77pncbef59f4k1qe83o' \\\n -H 'Authorization: Bearer kno8tcdotpbx3dj1gzcbx9jrqy'\n"
}
]
}
},
"/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.\n\n__Minimum server version__: 5.50\n\n##### Permissions\nMust be authenticated and user must belong to at least one channel shared with the remote cluster.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nremoteID := \"4xp9fdt77pncbef59f4k1qe83o\"\n\ninfo, err := Client.GetRemoteClusterInfo(remoteID)\n"
},
{
"lang": "curl",
"source": "curl -X POST \\\n 'http://your-mattermost-url.com/api/v4/sharedchannels/getremote/4xp9fdt77pncbef59f4k1qe83o' \\\n -H 'Authorization: Bearer kno8tcdotpbx3dj1gzcbx9jrqy'\n"
}
]
}
},
"/opengraph": {
"post": {
"tags": [
"OpenGraph"
],
"summary": "Get open graph metadata for url",
"description": "Get Open Graph Metadata for a specif URL. Use the Open Graph protocol to get some generic metadata about a URL. Used for creating link previews.\n\n__Minimum server version__: 3.10\n\n##### Permissions\nNo permission required but must be logged in.\n",
"operationId": "OpenGraph",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"url"
],
"properties": {
"url": {
"type": "string",
"description": "The URL to get Open Graph Metadata."
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Open Graph retrieval successful",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OpenGraph"
}
}
}
},
"501": {
"$ref": "#/components/responses/NotImplemented"
}
}
}
},
"/reactions": {
"post": {
"tags": [
"reactions"
],
"summary": "Create a reaction",
"description": "Create a reaction.\n##### Permissions\nMust have `read_channel` permission for the channel the post is in.\n",
"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"
}
}
}
},
"/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.\n##### Permissions\nMust have `read_channel` permission for the channel the post is in.\n",
"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"
}
}
}
},
"/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.\n##### Permissions\nMust be user or have `manage_system` permission.\n",
"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"
}
}
}
},
"/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.\n##### Permissions\nMust have `read_channel` permission for the channel the post is in.\n\n__Minimum server version__: 5.8\n",
"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"
}
}
}
},
"/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.\n__Minimum server version: 5.6__\n",
"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"
}
}
}
},
"/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.\n__Minimum server version: 5.6__\n",
"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"
}
}
}
},
"/bots": {
"post": {
"tags": [
"bots"
],
"summary": "Create a bot",
"description": "Create a new bot account on the system. Username is required.\n##### Permissions\nMust have `create_bot` permission.\n__Minimum server version__: 5.10\n",
"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"
}
},
"x-code-samples": [
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$resp = $driver->getBotModel()->createBot([\n \"username\" => \"userbot\",\n \"display_name\" => \"AwesomeBot\",\n \"description\" => \"test bot\"\n]);\n\nif ($resp->getStatusCode() == 200) {\n $createdBot = json_decode($resp->getBody());\n}\n"
}
]
},
"get": {
"tags": [
"bots"
],
"summary": "Get bots",
"description": "Get a page of a list of bots.\n##### Permissions\nMust have `read_bots` permission for bots you are managing, and `read_others_bots` permission for bots others are managing.\n__Minimum server version__: 5.10\n",
"operationId": "GetBots",
"parameters": [
{
"name": "page",
"in": "query",
"description": "The page to select.",
"schema": {
"type": "integer",
"default": 0
}
},
{
"name": "per_page",
"in": "query",
"description": "The number of users per page. There is a maximum limit of 200 users per page.",
"schema": {
"type": "integer",
"default": 60
}
},
{
"name": "include_deleted",
"in": "query",
"description": "If deleted bots should be returned.",
"schema": {
"type": "boolean"
}
},
{
"name": "only_orphaned",
"in": "query",
"description": "When true, only orphaned bots will be returned. A bot is consitered orphaned if it's 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"
}
},
"x-code-samples": [
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$resp = $driver->getBotModel()->getBots([\n \"page\" => 0,\n \"per_page\" => 60,\n \"include_deleted\" => true,\n \"only_orphaned\" => true,\n]);\n\nif ($resp->getStatusCode() == 200) {\n $bots = json_decode($resp->getBody());\n}\n"
}
]
}
},
"/bots/{bot_user_id}": {
"put": {
"tags": [
"bots"
],
"summary": "Patch a bot",
"description": "Partially update a bot by providing only the fields you want to update. Omitted fields will not be updated. The fields that can be updated are defined in the request body, all other provided fields will be ignored.\n##### Permissions\nMust have `manage_bots` permission. \n__Minimum server version__: 5.10\n",
"operationId": "PatchBot",
"parameters": [
{
"name": "bot_user_id",
"in": "path",
"description": "Bot user ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"description": "Bot to be created",
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"username"
],
"properties": {
"username": {
"type": "string"
},
"display_name": {
"type": "string"
},
"description": {
"type": "string"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Bot patch successful",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Bot"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
},
"x-code-samples": [
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$botUserID = \"4xp9fdt77pncbef59f4k1qe83o\";\n\n$resp = $driver->getBotModel()->patchBot($botUserID, [\n \"username\" => \"userbot2\",\n \"display_name\" => \"AwesomeBot2\",\n \"description\" => \"test bot2\"\n]);\n\nif ($resp->getStatusCode() == 200) {\n $bot = json_decode($resp->getBody());\n}\n"
}
]
},
"get": {
"tags": [
"bots"
],
"summary": "Get a bot",
"description": "Get a bot specified by its bot id.\n##### Permissions\nMust have `read_bots` permission for bots you are managing, and `read_others_bots` permission for bots others are managing.\n__Minimum server version__: 5.10\n",
"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"
}
},
"x-code-samples": [
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$botUserID = \"4xp9fdt77pncbef59f4k1qe83o\";\n\n$resp = $driver->getBotModel()->getBot($botUserID, [\n \"include_deleted\" => true,\n]);\n\nif ($resp->getStatusCode() == 200) {\n $bot = json_decode($resp->getBody());\n}\n"
}
]
}
},
"/bots/{bot_user_id}/disable": {
"post": {
"tags": [
"bots"
],
"summary": "Disable a bot",
"description": "Disable a bot.\n##### Permissions\nMust have `manage_bots` permission. \n__Minimum server version__: 5.10\n",
"operationId": "DisableBot",
"parameters": [
{
"name": "bot_user_id",
"in": "path",
"description": "Bot user ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Bot successfully disabled.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Bot"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
},
"x-code-samples": [
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$botUserID = \"4xp9fdt77pncbef59f4k1qe83o\";\n\n$resp = $driver->getBotModel()->disableBot($botUserID);\n\nif ($resp->getStatusCode() == 200) {\n $disabledBot = json_decode($resp->getBody());\n}\n"
}
]
}
},
"/bots/{bot_user_id}/enable": {
"post": {
"tags": [
"bots"
],
"summary": "Enable a bot",
"description": "Enable a bot.\n##### Permissions\nMust have `manage_bots` permission. \n__Minimum server version__: 5.10\n",
"operationId": "EnableBot",
"parameters": [
{
"name": "bot_user_id",
"in": "path",
"description": "Bot user ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Bot successfully enabled.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Bot"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
},
"x-code-samples": [
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$botUserID = \"4xp9fdt77pncbef59f4k1qe83o\";\n\n$resp = $driver->getBotModel()->enableBot($botUserID);\n\nif ($resp->getStatusCode() == 200) {\n $enabledBot = json_decode($resp->getBody());\n}\n"
}
]
}
},
"/bots/{bot_user_id}/assign/{user_id}": {
"post": {
"tags": [
"bots"
],
"summary": "Assign a bot to a user",
"description": "Assign a bot to a specified user.\n##### Permissions\nMust have `manage_bots` permission. \n__Minimum server version__: 5.10\n",
"operationId": "AssignBot",
"parameters": [
{
"name": "bot_user_id",
"in": "path",
"description": "Bot user ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "user_id",
"in": "path",
"description": "The user ID to assign the bot to.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Bot successfully assigned.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Bot"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
},
"x-code-samples": [
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$botUserID = \"4xp9fdt77pncbef59f4k1qe83o\";\n$userID = \"adWv1qPZmHdtxk7Lmqh6RtxWxS\";\n\n$resp = $driver->getBotModel()->assignBotToUser($botUserID, $userID);\n\nif ($resp->getStatusCode() == 200) {\n $assignedBot = json_decode($resp->getBody());\n}\n"
}
]
}
},
"/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.\n##### Permissions\nMust be logged in.\n__Minimum server version__: 5.14\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nbotUserID := \"4xp9fdt77pncbef59f4k1qe83o\"\n\ndata, resp := Client.GetBotIconImage(botUserID)\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$botUserID = \"4xp9fdt77pncbef59f4k1qe83o\";\n\n$resp = $driver->getBotModel()->getBotIcon($botUserID);\n\nif ($resp->getStatusCode() == 200) {\n $data = json_decode($resp->getBody());\n}\n"
}
]
},
"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.\n##### Permissions\nMust have `manage_bots` permission.\n__Minimum server version__: 5.14\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import (\n \"io/ioutil\"\n \"log\"\n\n \"github.com/mattermost/mattermost-server/v5/model\"\n)\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\ndata, err := ioutil.ReadFile(\"icon_image.svg\")\nif err != nil {\n log.Fatal(err)\n}\n\nbotUserID := \"4xp9fdt77pncbef59f4k1qe83o\"\n\nok, resp := Client.SetBotIconImage(botUserID, data)\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$botUserID = \"4xp9fdt77pncbef59f4k1qe83o\";\n$resource = fopen(\"icon_image.svg\", 'rb');\n\nif ($resource === false) {\n throw new \\Exeption(\"Failure.\");\n}\n\n$data = new \\GuzzleHttp\\Psr7\\Stream($resource);\n\n$resp = $driver->getBotModel()->setBotIcon($botUserID, [\n \"image\" => $data,\n]);\n\nfclose($resource);\n\nif ($resp->getStatusCode() == 200) {\n $ok = json_decode($resp->getBody())->status;\n}\n"
}
]
},
"delete": {
"tags": [
"bots"
],
"summary": "Delete bot's LHS icon image",
"description": "Delete bot's LHS icon image based on bot_user_id string parameter.\n##### Permissions\nMust have `manage_bots` permission.\n__Minimum server version__: 5.14\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nbotUserID := \"4xp9fdt77pncbef59f4k1qe83o\"\n\nok, resp := Client.DeleteBotIconImage(botUserID)\n"
},
{
"lang": "PHP",
"source": "require 'vendor/autoload.php';\n\nuse \\Gnello\\Mattermost\\Driver;\n\n$container = new \\Pimple\\Container([\n \"driver\" => [\n \"url\" => \"https://your-mattermost-url.com\",\n \"login_id\" => \"email@domain.com\",\n \"password\" => \"Password1\",\n ]\n]);\n\n$driver = new Driver($container);\n$driver->authenticate();\n\n$botUserID = \"4xp9fdt77pncbef59f4k1qe83o\";\n\n$resp = $driver->getBotModel()->deleteBotIcon($botUserID);\n\nif ($resp->getStatusCode() == 200) {\n $ok = json_decode($resp->getBody())->status;\n}\n"
}
]
}
},
"/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.\n\n__Minimum server version__: 5.26\n\n##### Permissions\nMust have `manage_system` permission.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\n\nuserId := \"BbaYBYDV5IDOZFiJGBSzkw1k5u\"\npatch := &model.UserPatch{}\npatch.Email = model.NewString(\"test@domain.com\")\npatch.Username = model.NewString(\"testUsername\")\npatch.Password = model.NewString(\"password\")\n\nuser, resp := Client.ConvertBotToUser(userId, userPatch, false)\n"
}
]
}
},
"/cloud/products": {
"get": {
"tags": [
"cloud"
],
"summary": "Get cloud products",
"description": "Retrieve a list of all products that are offered for Mattermost Cloud.\n##### Permissions\nMust have `manage_system` permission and be licensed for Cloud.\n__Minimum server version__: 5.28 __Note:__ This is intended for internal use and is subject to change.\n",
"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"
}
}
}
},
"/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.\n\n##### Permissions\n\nMust have `manage_system` permission and be licensed for Cloud.\n\n__Minimum server version__: 5.28\n__Note:__: This is intended for internal use and is subject to change.\n",
"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"
}
}
}
},
"/cloud/payment/confirm": {
"post": {
"tags": [
"cloud"
],
"summary": "Completes the payment setup intent",
"description": "Confirms the payment setup intent initiated when posting to `/cloud/payment`.\n##### Permissions\nMust have `manage_system` permission and be licensed for Cloud.\n__Minimum server version__: 5.28\n__Note:__ This is intended for internal use and is subject to change.\n",
"operationId": "ConfirmCustomerPayment",
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"stripe_setup_intent_id": {
"type": "string"
}
},
"required": [
"certificate"
]
}
}
}
},
"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"
}
}
}
},
"/cloud/customer": {
"get": {
"tags": [
"cloud"
],
"summary": "Get cloud customer",
"description": "Retrieves the customer information for the Mattermost Cloud customer bound to this installation.\n##### Permissions\nMust have `manage_system` permission and be licensed for Cloud.\n__Minimum server version__: 5.28 __Note:__ This is intended for internal use and is subject to change.\n",
"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.\n##### Permissions\nMust have `manage_system` permission and be licensed for Cloud.\n__Minimum server version__: 5.29 __Note:__ This is intended for internal use and is subject to change.\n",
"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"
}
}
}
},
"/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.\n##### Permissions\nMust have `manage_system` permission and be licensed for Cloud.\n__Minimum server version__: 5.29 __Note:__ This is intended for internal use and is subject to change.\n",
"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"
}
}
}
},
"/cloud/subscription": {
"get": {
"tags": [
"cloud"
],
"summary": "Get cloud subscription",
"description": "Retrieves the subscription information for the Mattermost Cloud customer bound to this installation.\n##### Permissions\nMust have `manage_system` permission and be licensed for Cloud.\n__Minimum server version__: 5.28 __Note:__ This is intended for internal use and is subject to change.\n",
"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"
}
}
}
},
"/cloud/subscription/invoices": {
"get": {
"tags": [
"cloud"
],
"summary": "Get cloud subscription invoices",
"description": "Retrieves the invoices for the subscription bound to this installation.\n##### Permissions\nMust have `manage_system` permission and be licensed for Cloud.\n__Minimum server version__: 5.30 __Note:__ This is intended for internal use and is subject to change.\n",
"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"
}
}
}
},
"/cloud/subscription/invoices/{invoice_id}/pdf": {
"get": {
"tags": [
"cloud"
],
"summary": "Get cloud invoice PDF",
"description": "Retrieves the PDF for the invoice passed as parameter\n##### Permissions\nMust have `manage_system` permission and be licensed for Cloud.\n__Minimum server version__: 5.30 __Note:__ This is intended for internal use and is subject to change.\n",
"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"
}
}
}
},
"/cloud/webhook": {
"post": {
"tags": [
"cloud"
],
"summary": "POST endpoint for CWS Webhooks",
"description": "An endpoint for processing webhooks from the Customer Portal\n##### Permissions\nThis endpoint should only be accessed by CWS, in a Mattermost Cloud instance\n__Minimum server version__: 5.30 __Note:__ This is intended for internal use and is subject to change.\n",
"operationId": "PostEndpointForCwsWebhooks",
"responses": {
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"501": {
"$ref": "#/components/responses/NotImplemented"
}
}
}
},
"/cloud/subscription/stats": {
"get": {
"tags": [
"cloud"
],
"summary": "GET endpoint for cloud subscription stats",
"description": "An endpoint that returns stats about a user's subscription. For example remaining seats on a free tier\n##### Permissions\nThis endpoint should only be accessed in a Mattermost Cloud instance\n__Minimum server version__: 5.34 __Note:__ This is intended for internal use and is subject to change.\n",
"operationId": "GetSubscriptionStats",
"responses": {
"200": {
"description": "Cloud subscription stats returned successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubscriptionStats"
}
}
}
},
"500": {
"$ref": "#/components/responses/InternalServerError"
}
}
}
},
"/cloud/subscription/limitreached/invite": {
"post": {
"tags": [
"cloud"
],
"summary": "POST endpoint for triggering sending emails to admin with request to upgrade workspace",
"description": "An endpoint that triggers sending emails to all sys admins to request them to upgrade the workspace when a user tries to invite more users ##### Permissions\nThis endpoint should only be accessed in a Mattermost Cloud instance\n__Minimum server version__: 5.34 __Note:__ This is intended for internal use and is subject to change.\n",
"operationId": "SendAdminUpgradeRequestEmail",
"responses": {
"200": {
"description": "Email sent to at least one of the system administrators"
},
"413": {
"$ref": "#/components/responses/TooLarge"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
},
"501": {
"$ref": "#/components/responses/NotImplemented"
}
}
}
},
"/cloud/subscription/limitreached/join": {
"post": {
"tags": [
"cloud"
],
"summary": "POST endpoint for triggering sending emails to admin with request to upgrade workspace",
"description": "An endpoint that triggers sending emails to all sys admins to request them to upgrade the workspace when a user tries to join the workspace ##### Permissions\nThis endpoint should only be accessed in a Mattermost Cloud instance\n__Minimum server version__: 5.34 __Note:__ This is intended for internal use and is subject to change.\n",
"operationId": "SendAdminUpgradeRequestEmailOnJoin",
"responses": {
"200": {
"description": "Email sent to at least one of the system administrators"
},
"413": {
"$ref": "#/components/responses/TooLarge"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
},
"501": {
"$ref": "#/components/responses/NotImplemented"
}
}
}
},
"/permissions/ancillary": {
"get": {
"tags": [
"permissions"
],
"summary": "Return all system console subsection ancillary permissions",
"description": "Returns all the ancillary permissions for the corresponding system console subsection permissions appended to the requested permission subsections.\n\n__Minimum server version__: 5.35\n",
"operationId": "GetAncillaryPermissions",
"parameters": [
{
"name": "subsection_permissions",
"in": "query",
"description": "The subsection permissions to return the ancillary permissions for. These values are comma seperated. Ex. subsection_permissions=sysconsole_read_reporting_site_statistics,sysconsole_write_reporting_site_statistics,sysconsole_write_user_management_channels\n",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successfully returned all ancillary and requested permissions",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
}
}
}
},
"/imports": {
"get": {
"tags": [
"imports"
],
"summary": "List import files",
"description": "Lists all available import files.\n\n__Minimum server version__: 5.31\n##### Permissions\nMust have `manage_system` permissions.\n",
"operationId": "ListImports",
"responses": {
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\nimports, response := Client.ListImports()\n"
},
{
"lang": "Curl",
"source": "curl 'http://localhost:8065/api/v4/imports' \\\n-H 'Authorization: Bearer 9kg8nqrnxprd9jbykqeg4r51hw'\n"
}
]
}
},
"/exports": {
"get": {
"tags": [
"exports"
],
"summary": "List export files",
"description": "Lists all available export files.\n__Minimum server version__: 5.33\n##### Permissions\nMust have `manage_system` permissions.\n",
"operationId": "ListExports",
"responses": {
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\" Client := model.NewAPIv4Client(\"https://your-mattermost-url.com\") Client.Login(\"email@domain.com\", \"Password1\")\nexports, response := Client.ListExports()\n"
},
{
"lang": "Curl",
"source": "curl 'http://localhost:8065/api/v4/exports' \\\n-H 'Authorization: Bearer 9kg8nqrnxprd9jbykqeg4r51hw'\n"
}
]
}
},
"/exports/{export_name}": {
"get": {
"tags": [
"exports"
],
"summary": "Download an export file",
"description": "Downloads an export file.\n\n\n__Minimum server version__: 5.33\n\n##### Permissions\n\nMust have `manage_system` permissions.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import (\n \"os\"\n \n \"github.com/mattermost/mattermost-server/v5/model\"\n}\n\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\noutFile, _ := os.Create(\"export.zip\")\n\nn, response := Client.DownloadExport(\"export.zip\", outFile, 0)\n"
},
{
"lang": "Curl",
"source": "curl 'http://localhost:8065/api/v4/exports/export.zip' \\\n-H 'Authorization: Bearer 9kg8nqrnxprd9jbykqeg4r51hw'\n"
}
]
},
"delete": {
"tags": [
"exports"
],
"summary": "Delete an export file",
"description": "Deletes an export file.\n\n\n__Minimum server version__: 5.33\n\n##### Permissions\n\nMust have `manage_system` permissions.\n",
"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"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/v5/model\"\n\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"email@domain.com\", \"Password1\")\n\nok, response := Client.DeleteExport(\"export.zip\")\n"
},
{
"lang": "Curl",
"source": "curl -X DELETE 'http://localhost:8065/api/v4/exports/export.zip' \\\n-H 'Authorization: Bearer 9kg8nqrnxprd9jbykqeg4r51hw'\n"
}
]
}
}
},
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "Token"
}
},
"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"
}
}
}
}
},
"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"
},
"last_picture_update": {
"type": "integer"
},
"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"
}
}
},
"Team": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"create_at": {
"description": "The time in milliseconds a team was created",
"type": "integer",
"format": "int64"
},
"update_at": {
"description": "The time in milliseconds a team was last updated",
"type": "integer",
"format": "int64"
},
"delete_at": {
"description": "The time in milliseconds a team was deleted",
"type": "integer",
"format": "int64"
},
"display_name": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"email": {
"type": "string"
},
"type": {
"type": "string"
},
"allowed_domains": {
"type": "string"
},
"invite_id": {
"type": "string"
},
"allow_open_invite": {
"type": "boolean"
},
"policy_id": {
"type": "string",
"description": "The data retention policy to which this team has been assigned. If no such policy exists, or the caller does not have the `sysconsole_read_compliance_data_retention` permission, this field will be null."
}
}
},
"TeamStats": {
"type": "object",
"properties": {
"team_id": {
"type": "string"
},
"total_member_count": {
"type": "integer"
},
"active_member_count": {
"type": "integer"
}
}
},
"TeamExists": {
"type": "object",
"properties": {
"exists": {
"type": "boolean"
}
}
},
"Channel": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"create_at": {
"description": "The time in milliseconds a channel was created",
"type": "integer",
"format": "int64"
},
"update_at": {
"description": "The time in milliseconds a channel was last updated",
"type": "integer",
"format": "int64"
},
"delete_at": {
"description": "The time in milliseconds a channel was deleted",
"type": "integer",
"format": "int64"
},
"team_id": {
"type": "string"
},
"type": {
"type": "string"
},
"display_name": {
"type": "string"
},
"name": {
"type": "string"
},
"header": {
"type": "string"
},
"purpose": {
"type": "string"
},
"last_post_at": {
"description": "The time in milliseconds of the last post of a channel",
"type": "integer"
},
"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"
}
},
"Post": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"create_at": {
"description": "The time in milliseconds a post was created",
"type": "integer",
"format": "int64"
},
"update_at": {
"description": "The time in milliseconds a post was last updated",
"type": "integer",
"format": "int64"
},
"delete_at": {
"description": "The time in milliseconds a post was deleted",
"type": "integer",
"format": "int64"
},
"edit_at": {
"type": "integer",
"format": "int64"
},
"user_id": {
"type": "string"
},
"channel_id": {
"type": "string"
},
"root_id": {
"type": "string"
},
"original_id": {
"type": "string"
},
"message": {
"type": "string"
},
"type": {
"type": "string"
},
"props": {
"type": "object"
},
"hashtag": {
"type": "string"
},
"file_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"pending_post_id": {
"type": "string"
},
"metadata": {
"$ref": "#/components/schemas/PostMetadata"
}
}
},
"FileInfoList": {
"type": "object",
"properties": {
"order": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"file_info_id1",
"file_info_id2"
]
},
"file_infos": {
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/FileInfo"
}
},
"next_file_id": {
"type": "string",
"description": "The ID of next file info. Not omitted when empty or not relevant."
},
"prev_file_id": {
"type": "string",
"description": "The ID of previous file info. Not omitted when empty or not relevant."
}
}
},
"PostList": {
"type": "object",
"properties": {
"order": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"post_id1",
"post_id12"
]
},
"posts": {
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/Post"
}
},
"next_post_id": {
"type": "string",
"description": "The ID of next post. Not omitted when empty or not relevant."
},
"prev_post_id": {
"type": "string",
"description": "The ID of previous post. Not omitted when empty or not relevant."
}
}
},
"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.\n",
"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.\nThis field will be null for non-OpenGraph embeds.\n"
}
}
}
},
"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.\n",
"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.\n",
"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.\n",
"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.\n",
"items": {
"$ref": "#/components/schemas/Reaction"
}
}
}
},
"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"
}
}
},
"Emoji": {
"type": "object",
"properties": {
"id": {
"description": "The ID of the emoji",
"type": "string"
},
"creator_id": {
"description": "The ID of the user that made the emoji",
"type": "string"
},
"name": {
"description": "The name of the emoji",
"type": "string"
},
"create_at": {
"description": "The time in milliseconds the emoji was made",
"type": "integer",
"format": "int64"
},
"update_at": {
"description": "The time in milliseconds the emoji was last updated",
"type": "integer",
"format": "int64"
},
"delete_at": {
"description": "The time in milliseconds the emoji was deleted",
"type": "integer",
"format": "int64"
}
}
},
"Command": {
"type": "object",
"properties": {
"id": {
"description": "The ID of the slash command",
"type": "string"
},
"token": {
"description": "The token which is used to verify the source of the payload",
"type": "string"
},
"create_at": {
"description": "The time in milliseconds the command was created",
"type": "integer"
},
"update_at": {
"description": "The time in milliseconds the command was last updated",
"type": "integer",
"format": "int64"
},
"delete_at": {
"description": "The time in milliseconds the command was deleted, 0 if never deleted",
"type": "integer",
"format": "int64"
},
"creator_id": {
"description": "The user id for the commands creator",
"type": "string"
},
"team_id": {
"description": "The team id for which this command is configured",
"type": "string"
},
"trigger": {
"description": "The string that triggers this command",
"type": "string"
},
"method": {
"description": "Is the trigger done with HTTP Get ('G') or HTTP Post ('P')",
"type": "string"
},
"username": {
"description": "What is the username for the response post",
"type": "string"
},
"icon_url": {
"description": "The url to find the icon for this users avatar",
"type": "string"
},
"auto_complete": {
"description": "Use auto complete for this command",
"type": "boolean"
},
"auto_complete_desc": {
"description": "The description for this command shown when selecting the command",
"type": "string"
},
"auto_complete_hint": {
"description": "The hint for this command",
"type": "string"
},
"display_name": {
"description": "Display name for the command",
"type": "string"
},
"description": {
"description": "Description for this command",
"type": "string"
},
"url": {
"description": "The URL that is triggered",
"type": "string"
}
}
},
"AutocompleteSuggestion": {
"type": "object",
"properties": {
"Complete": {
"description": "Completed suggestion",
"type": "string"
},
"Suggestion": {
"description": "Predicted text user might want to input",
"type": "string"
},
"Hint": {
"description": "Hint about suggested input",
"type": "string"
},
"Description": {
"description": "Description of the suggested command",
"type": "string"
},
"IconData": {
"description": "Base64 encoded svg image",
"type": "string"
}
}
},
"CommandResponse": {
"type": "object",
"properties": {
"ResponseType": {
"description": "The response type either in_channel or ephemeral",
"type": "string"
},
"Text": {
"type": "string"
},
"Username": {
"type": "string"
},
"IconURL": {
"type": "string"
},
"GotoLocation": {
"type": "string"
},
"Attachments": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SlackAttachment"
}
}
}
},
"SlackAttachment": {
"type": "object",
"properties": {
"Id": {
"type": "string"
},
"Fallback": {
"type": "string"
},
"Color": {
"type": "string"
},
"Pretext": {
"type": "string"
},
"AuthorName": {
"type": "string"
},
"AuthorLink": {
"type": "string"
},
"AuthorIcon": {
"type": "string"
},
"Title": {
"type": "string"
},
"TitleLink": {
"type": "string"
},
"Text": {
"type": "string"
},
"Fields": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SlackAttachmentField"
}
},
"ImageURL": {
"type": "string"
},
"ThumbURL": {
"type": "string"
},
"Footer": {
"type": "string"
},
"FooterIcon": {
"type": "string"
},
"Timestamp": {
"description": "The timestamp of the slack attachment, either type of string or integer",
"type": "string"
}
}
},
"SlackAttachmentField": {
"type": "object",
"properties": {
"Title": {
"type": "string"
},
"Value": {
"description": "The value of the attachment, set as string but capable with golang interface",
"type": "string"
},
"Short": {
"type": "boolean"
}
}
},
"StatusOK": {
"type": "object",
"properties": {
"status": {
"description": "Will contain \"ok\" if the request was successful and there was nothing else to return",
"type": "string"
}
}
},
"OpenGraph": {
"type": "object",
"description": "OpenGraph metadata of a webpage",
"properties": {
"type": {
"type": "string"
},
"url": {
"type": "string"
},
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"determiner": {
"type": "string"
},
"site_name": {
"type": "string"
},
"locale": {
"type": "string"
},
"locales_alternate": {
"type": "array",
"items": {
"type": "string"
}
},
"images": {
"type": "array",
"items": {
"type": "object",
"description": "Image object used in OpenGraph metadata of a webpage",
"properties": {
"url": {
"type": "string"
},
"secure_url": {
"type": "string"
},
"type": {
"type": "string"
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
}
}
}
},
"videos": {
"type": "array",
"items": {
"type": "object",
"description": "Video object used in OpenGraph metadata of a webpage",
"properties": {
"url": {
"type": "string"
},
"secure_url": {
"type": "string"
},
"type": {
"type": "string"
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
}
}
}
},
"audios": {
"type": "array",
"items": {
"type": "object",
"description": "Audio object used in OpenGraph metadata of a webpage",
"properties": {
"url": {
"type": "string"
},
"secure_url": {
"type": "string"
},
"type": {
"type": "string"
}
}
}
},
"article": {
"type": "object",
"description": "Article object used in OpenGraph metadata of a webpage, if type is article",
"properties": {
"published_time": {
"type": "string"
},
"modified_time": {
"type": "string"
},
"expiration_time": {
"type": "string"
},
"section": {
"type": "string"
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"authors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"first_name": {
"type": "string"
},
"last_name": {
"type": "string"
},
"username": {
"type": "string"
},
"gender": {
"type": "string"
}
}
}
}
}
},
"book": {
"type": "object",
"description": "Book object used in OpenGraph metadata of a webpage, if type is book",
"properties": {
"isbn": {
"type": "string"
},
"release_date": {
"type": "string"
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"authors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"first_name": {
"type": "string"
},
"last_name": {
"type": "string"
},
"username": {
"type": "string"
},
"gender": {
"type": "string"
}
}
}
}
}
},
"profile": {
"type": "object",
"properties": {
"first_name": {
"type": "string"
},
"last_name": {
"type": "string"
},
"username": {
"type": "string"
},
"gender": {
"type": "string"
}
}
}
}
},
"Audit": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"create_at": {
"description": "The time in milliseconds a audit was created",
"type": "integer",
"format": "int64"
},
"user_id": {
"type": "string"
},
"action": {
"type": "string"
},
"extra_info": {
"type": "string"
},
"ip_address": {
"type": "string"
},
"session_id": {
"type": "string"
}
}
},
"Config": {
"type": "object",
"properties": {
"ServiceSettings": {
"type": "object",
"properties": {
"SiteURL": {
"type": "string"
},
"ListenAddress": {
"type": "string"
},
"ConnectionSecurity": {
"type": "string"
},
"TLSCertFile": {
"type": "string"
},
"TLSKeyFile": {
"type": "string"
},
"UseLetsEncrypt": {
"type": "boolean"
},
"LetsEncryptCertificateCacheFile": {
"type": "string"
},
"Forward80To443": {
"type": "boolean"
},
"ReadTimeout": {
"type": "integer"
},
"WriteTimeout": {
"type": "integer"
},
"MaximumLoginAttempts": {
"type": "integer"
},
"SegmentDeveloperKey": {
"type": "string"
},
"GoogleDeveloperKey": {
"type": "string"
},
"EnableOAuthServiceProvider": {
"type": "boolean"
},
"EnableIncomingWebhooks": {
"type": "boolean"
},
"EnableOutgoingWebhooks": {
"type": "boolean"
},
"EnableCommands": {
"type": "boolean"
},
"EnableOnlyAdminIntegrations": {
"type": "boolean"
},
"EnablePostUsernameOverride": {
"type": "boolean"
},
"EnablePostIconOverride": {
"type": "boolean"
},
"EnableTesting": {
"type": "boolean"
},
"EnableDeveloper": {
"type": "boolean"
},
"EnableSecurityFixAlert": {
"type": "boolean"
},
"EnableInsecureOutgoingConnections": {
"type": "boolean"
},
"EnableMultifactorAuthentication": {
"type": "boolean"
},
"EnforceMultifactorAuthentication": {
"type": "boolean"
},
"AllowCorsFrom": {
"type": "string"
},
"SessionLengthWebInDays": {
"type": "integer"
},
"SessionLengthMobileInDays": {
"type": "integer"
},
"SessionLengthSSOInDays": {
"type": "integer"
},
"SessionCacheInMinutes": {
"type": "integer"
},
"WebsocketSecurePort": {
"type": "integer"
},
"WebsocketPort": {
"type": "integer"
},
"WebserverMode": {
"type": "string"
},
"EnableCustomEmoji": {
"type": "boolean"
},
"RestrictCustomEmojiCreation": {
"type": "string"
}
}
},
"TeamSettings": {
"type": "object",
"properties": {
"SiteName": {
"type": "string"
},
"MaxUsersPerTeam": {
"type": "integer"
},
"EnableTeamCreation": {
"type": "boolean"
},
"EnableUserCreation": {
"type": "boolean"
},
"EnableOpenServer": {
"type": "boolean"
},
"RestrictCreationToDomains": {
"type": "string"
},
"EnableCustomBrand": {
"type": "boolean"
},
"CustomBrandText": {
"type": "string"
},
"CustomDescriptionText": {
"type": "string"
},
"RestrictDirectMessage": {
"type": "string"
},
"RestrictTeamInvite": {
"type": "string"
},
"RestrictPublicChannelManagement": {
"type": "string"
},
"RestrictPrivateChannelManagement": {
"type": "string"
},
"RestrictPublicChannelCreation": {
"type": "string"
},
"RestrictPrivateChannelCreation": {
"type": "string"
},
"RestrictPublicChannelDeletion": {
"type": "string"
},
"RestrictPrivateChannelDeletion": {
"type": "string"
},
"UserStatusAwayTimeout": {
"type": "integer"
},
"MaxChannelsPerTeam": {
"type": "integer"
},
"MaxNotificationsPerChannel": {
"type": "integer"
}
}
},
"SqlSettings": {
"type": "object",
"properties": {
"DriverName": {
"type": "string"
},
"DataSource": {
"type": "string"
},
"DataSourceReplicas": {
"type": "array",
"items": {
"type": "string"
}
},
"MaxIdleConns": {
"type": "integer"
},
"MaxOpenConns": {
"type": "integer"
},
"Trace": {
"type": "boolean"
},
"AtRestEncryptKey": {
"type": "string"
}
}
},
"LogSettings": {
"type": "object",
"properties": {
"EnableConsole": {
"type": "boolean"
},
"ConsoleLevel": {
"type": "string"
},
"EnableFile": {
"type": "boolean"
},
"FileLevel": {
"type": "string"
},
"FileLocation": {
"type": "string"
},
"EnableWebhookDebugging": {
"type": "boolean"
},
"EnableDiagnostics": {
"type": "boolean"
}
}
},
"PasswordSettings": {
"type": "object",
"properties": {
"MinimumLength": {
"type": "integer"
},
"Lowercase": {
"type": "boolean"
},
"Number": {
"type": "boolean"
},
"Uppercase": {
"type": "boolean"
},
"Symbol": {
"type": "boolean"
}
}
},
"FileSettings": {
"type": "object",
"properties": {
"MaxFileSize": {
"type": "integer"
},
"DriverName": {
"type": "string"
},
"Directory": {
"type": "string"
},
"EnablePublicLink": {
"type": "boolean"
},
"PublicLinkSalt": {
"type": "string"
},
"ThumbnailWidth": {
"type": "integer"
},
"ThumbnailHeight": {
"type": "integer"
},
"PreviewWidth": {
"type": "integer"
},
"PreviewHeight": {
"type": "integer"
},
"ProfileWidth": {
"type": "integer"
},
"ProfileHeight": {
"type": "integer"
},
"InitialFont": {
"type": "string"
},
"AmazonS3AccessKeyId": {
"type": "string"
},
"AmazonS3SecretAccessKey": {
"type": "string"
},
"AmazonS3Bucket": {
"type": "string"
},
"AmazonS3Region": {
"type": "string"
},
"AmazonS3Endpoint": {
"type": "string"
},
"AmazonS3SSL": {
"type": "boolean"
}
}
},
"EmailSettings": {
"type": "object",
"properties": {
"EnableSignUpWithEmail": {
"type": "boolean"
},
"EnableSignInWithEmail": {
"type": "boolean"
},
"EnableSignInWithUsername": {
"type": "boolean"
},
"SendEmailNotifications": {
"type": "boolean"
},
"RequireEmailVerification": {
"type": "boolean"
},
"FeedbackName": {
"type": "string"
},
"FeedbackEmail": {
"type": "string"
},
"FeedbackOrganization": {
"type": "string"
},
"SMTPUsername": {
"type": "string"
},
"SMTPPassword": {
"type": "string"
},
"SMTPServer": {
"type": "string"
},
"SMTPPort": {
"type": "string"
},
"ConnectionSecurity": {
"type": "string"
},
"InviteSalt": {
"type": "string"
},
"PasswordResetSalt": {
"type": "string"
},
"SendPushNotifications": {
"type": "boolean"
},
"PushNotificationServer": {
"type": "string"
},
"PushNotificationContents": {
"type": "string"
},
"EnableEmailBatching": {
"type": "boolean"
},
"EmailBatchingBufferSize": {
"type": "integer"
},
"EmailBatchingInterval": {
"type": "integer"
}
}
},
"RateLimitSettings": {
"type": "object",
"properties": {
"Enable": {
"type": "boolean"
},
"PerSec": {
"type": "integer"
},
"MaxBurst": {
"type": "integer"
},
"MemoryStoreSize": {
"type": "integer"
},
"VaryByRemoteAddr": {
"type": "boolean"
},
"VaryByHeader": {
"type": "string"
}
}
},
"PrivacySettings": {
"type": "object",
"properties": {
"ShowEmailAddress": {
"type": "boolean"
},
"ShowFullName": {
"type": "boolean"
}
}
},
"SupportSettings": {
"type": "object",
"properties": {
"TermsOfServiceLink": {
"type": "string"
},
"PrivacyPolicyLink": {
"type": "string"
},
"AboutLink": {
"type": "string"
},
"HelpLink": {
"type": "string"
},
"ReportAProblemLink": {
"type": "string"
},
"SupportEmail": {
"type": "string"
}
}
},
"GitLabSettings": {
"type": "object",
"properties": {
"Enable": {
"type": "boolean"
},
"Secret": {
"type": "string"
},
"Id": {
"type": "string"
},
"Scope": {
"type": "string"
},
"AuthEndpoint": {
"type": "string"
},
"TokenEndpoint": {
"type": "string"
},
"UserApiEndpoint": {
"type": "string"
}
}
},
"GoogleSettings": {
"type": "object",
"properties": {
"Enable": {
"type": "boolean"
},
"Secret": {
"type": "string"
},
"Id": {
"type": "string"
},
"Scope": {
"type": "string"
},
"AuthEndpoint": {
"type": "string"
},
"TokenEndpoint": {
"type": "string"
},
"UserApiEndpoint": {
"type": "string"
}
}
},
"Office365Settings": {
"type": "object",
"properties": {
"Enable": {
"type": "boolean"
},
"Secret": {
"type": "string"
},
"Id": {
"type": "string"
},
"Scope": {
"type": "string"
},
"AuthEndpoint": {
"type": "string"
},
"TokenEndpoint": {
"type": "string"
},
"UserApiEndpoint": {
"type": "string"
}
}
},
"LdapSettings": {
"type": "object",
"properties": {
"Enable": {
"type": "boolean"
},
"LdapServer": {
"type": "string"
},
"LdapPort": {
"type": "integer"
},
"ConnectionSecurity": {
"type": "string"
},
"BaseDN": {
"type": "string"
},
"BindUsername": {
"type": "string"
},
"BindPassword": {
"type": "string"
},
"UserFilter": {
"type": "string"
},
"FirstNameAttribute": {
"type": "string"
},
"LastNameAttribute": {
"type": "string"
},
"EmailAttribute": {
"type": "string"
},
"UsernameAttribute": {
"type": "string"
},
"NicknameAttribute": {
"type": "string"
},
"IdAttribute": {
"type": "string"
},
"PositionAttribute": {
"type": "string"
},
"SyncIntervalMinutes": {
"type": "integer"
},
"SkipCertificateVerification": {
"type": "boolean"
},
"QueryTimeout": {
"type": "integer"
},
"MaxPageSize": {
"type": "integer"
},
"LoginFieldName": {
"type": "string"
}
}
},
"ComplianceSettings": {
"type": "object",
"properties": {
"Enable": {
"type": "boolean"
},
"Directory": {
"type": "string"
},
"EnableDaily": {
"type": "boolean"
}
}
},
"LocalizationSettings": {
"type": "object",
"properties": {
"DefaultServerLocale": {
"type": "string"
},
"DefaultClientLocale": {
"type": "string"
},
"AvailableLocales": {
"type": "string"
}
}
},
"SamlSettings": {
"type": "object",
"properties": {
"Enable": {
"type": "boolean"
},
"Verify": {
"type": "boolean"
},
"Encrypt": {
"type": "boolean"
},
"IdpUrl": {
"type": "string"
},
"IdpDescriptorUrl": {
"type": "string"
},
"AssertionConsumerServiceURL": {
"type": "string"
},
"IdpCertificateFile": {
"type": "string"
},
"PublicCertificateFile": {
"type": "string"
},
"PrivateKeyFile": {
"type": "string"
},
"FirstNameAttribute": {
"type": "string"
},
"LastNameAttribute": {
"type": "string"
},
"EmailAttribute": {
"type": "string"
},
"UsernameAttribute": {
"type": "string"
},
"NicknameAttribute": {
"type": "string"
},
"LocaleAttribute": {
"type": "string"
},
"PositionAttribute": {
"type": "string"
},
"LoginButtonText": {
"type": "string"
}
}
},
"NativeAppSettings": {
"type": "object",
"properties": {
"AppDownloadLink": {
"type": "string"
},
"AndroidAppDownloadLink": {
"type": "string"
},
"IosAppDownloadLink": {
"type": "string"
}
}
},
"ClusterSettings": {
"type": "object",
"properties": {
"Enable": {
"type": "boolean"
},
"InterNodeListenAddress": {
"type": "string"
},
"InterNodeUrls": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"MetricsSettings": {
"type": "object",
"properties": {
"Enable": {
"type": "boolean"
},
"BlockProfileRate": {
"type": "integer"
},
"ListenAddress": {
"type": "string"
}
}
},
"AnalyticsSettings": {
"type": "object",
"properties": {
"MaxUsersForStatistics": {
"type": "integer"
}
}
}
}
},
"EnvironmentConfig": {
"type": "object",
"properties": {
"ServiceSettings": {
"type": "object",
"properties": {
"SiteURL": {
"type": "boolean"
},
"ListenAddress": {
"type": "boolean"
},
"ConnectionSecurity": {
"type": "boolean"
},
"TLSCertFile": {
"type": "boolean"
},
"TLSKeyFile": {
"type": "boolean"
},
"UseLetsEncrypt": {
"type": "boolean"
},
"LetsEncryptCertificateCacheFile": {
"type": "boolean"
},
"Forward80To443": {
"type": "boolean"
},
"ReadTimeout": {
"type": "boolean"
},
"WriteTimeout": {
"type": "boolean"
},
"MaximumLoginAttempts": {
"type": "boolean"
},
"SegmentDeveloperKey": {
"type": "boolean"
},
"GoogleDeveloperKey": {
"type": "boolean"
},
"EnableOAuthServiceProvider": {
"type": "boolean"
},
"EnableIncomingWebhooks": {
"type": "boolean"
},
"EnableOutgoingWebhooks": {
"type": "boolean"
},
"EnableCommands": {
"type": "boolean"
},
"EnableOnlyAdminIntegrations": {
"type": "boolean"
},
"EnablePostUsernameOverride": {
"type": "boolean"
},
"EnablePostIconOverride": {
"type": "boolean"
},
"EnableTesting": {
"type": "boolean"
},
"EnableDeveloper": {
"type": "boolean"
},
"EnableSecurityFixAlert": {
"type": "boolean"
},
"EnableInsecureOutgoingConnections": {
"type": "boolean"
},
"EnableMultifactorAuthentication": {
"type": "boolean"
},
"EnforceMultifactorAuthentication": {
"type": "boolean"
},
"AllowCorsFrom": {
"type": "boolean"
},
"SessionLengthWebInDays": {
"type": "boolean"
},
"SessionLengthMobileInDays": {
"type": "boolean"
},
"SessionLengthSSOInDays": {
"type": "boolean"
},
"SessionCacheInMinutes": {
"type": "boolean"
},
"WebsocketSecurePort": {
"type": "boolean"
},
"WebsocketPort": {
"type": "boolean"
},
"WebserverMode": {
"type": "boolean"
},
"EnableCustomEmoji": {
"type": "boolean"
},
"RestrictCustomEmojiCreation": {
"type": "boolean"
}
}
},
"TeamSettings": {
"type": "object",
"properties": {
"SiteName": {
"type": "boolean"
},
"MaxUsersPerTeam": {
"type": "boolean"
},
"EnableTeamCreation": {
"type": "boolean"
},
"EnableUserCreation": {
"type": "boolean"
},
"EnableOpenServer": {
"type": "boolean"
},
"RestrictCreationToDomains": {
"type": "boolean"
},
"EnableCustomBrand": {
"type": "boolean"
},
"CustomBrandText": {
"type": "boolean"
},
"CustomDescriptionText": {
"type": "boolean"
},
"RestrictDirectMessage": {
"type": "boolean"
},
"RestrictTeamInvite": {
"type": "boolean"
},
"RestrictPublicChannelManagement": {
"type": "boolean"
},
"RestrictPrivateChannelManagement": {
"type": "boolean"
},
"RestrictPublicChannelCreation": {
"type": "boolean"
},
"RestrictPrivateChannelCreation": {
"type": "boolean"
},
"RestrictPublicChannelDeletion": {
"type": "boolean"
},
"RestrictPrivateChannelDeletion": {
"type": "boolean"
},
"UserStatusAwayTimeout": {
"type": "boolean"
},
"MaxChannelsPerTeam": {
"type": "boolean"
},
"MaxNotificationsPerChannel": {
"type": "boolean"
}
}
},
"SqlSettings": {
"type": "object",
"properties": {
"DriverName": {
"type": "boolean"
},
"DataSource": {
"type": "boolean"
},
"DataSourceReplicas": {
"type": "boolean"
},
"MaxIdleConns": {
"type": "boolean"
},
"MaxOpenConns": {
"type": "boolean"
},
"Trace": {
"type": "boolean"
},
"AtRestEncryptKey": {
"type": "boolean"
}
}
},
"LogSettings": {
"type": "object",
"properties": {
"EnableConsole": {
"type": "boolean"
},
"ConsoleLevel": {
"type": "boolean"
},
"EnableFile": {
"type": "boolean"
},
"FileLevel": {
"type": "boolean"
},
"FileLocation": {
"type": "boolean"
},
"EnableWebhookDebugging": {
"type": "boolean"
},
"EnableDiagnostics": {
"type": "boolean"
}
}
},
"PasswordSettings": {
"type": "object",
"properties": {
"MinimumLength": {
"type": "boolean"
},
"Lowercase": {
"type": "boolean"
},
"Number": {
"type": "boolean"
},
"Uppercase": {
"type": "boolean"
},
"Symbol": {
"type": "boolean"
}
}
},
"FileSettings": {
"type": "object",
"properties": {
"MaxFileSize": {
"type": "boolean"
},
"DriverName": {
"type": "boolean"
},
"Directory": {
"type": "boolean"
},
"EnablePublicLink": {
"type": "boolean"
},
"PublicLinkSalt": {
"type": "boolean"
},
"ThumbnailWidth": {
"type": "boolean"
},
"ThumbnailHeight": {
"type": "boolean"
},
"PreviewWidth": {
"type": "boolean"
},
"PreviewHeight": {
"type": "boolean"
},
"ProfileWidth": {
"type": "boolean"
},
"ProfileHeight": {
"type": "boolean"
},
"InitialFont": {
"type": "boolean"
},
"AmazonS3AccessKeyId": {
"type": "boolean"
},
"AmazonS3SecretAccessKey": {
"type": "boolean"
},
"AmazonS3Bucket": {
"type": "boolean"
},
"AmazonS3Region": {
"type": "boolean"
},
"AmazonS3Endpoint": {
"type": "boolean"
},
"AmazonS3SSL": {
"type": "boolean"
}
}
},
"EmailSettings": {
"type": "object",
"properties": {
"EnableSignUpWithEmail": {
"type": "boolean"
},
"EnableSignInWithEmail": {
"type": "boolean"
},
"EnableSignInWithUsername": {
"type": "boolean"
},
"SendEmailNotifications": {
"type": "boolean"
},
"RequireEmailVerification": {
"type": "boolean"
},
"FeedbackName": {
"type": "boolean"
},
"FeedbackEmail": {
"type": "boolean"
},
"FeedbackOrganization": {
"type": "boolean"
},
"SMTPUsername": {
"type": "boolean"
},
"SMTPPassword": {
"type": "boolean"
},
"SMTPServer": {
"type": "boolean"
},
"SMTPPort": {
"type": "boolean"
},
"ConnectionSecurity": {
"type": "boolean"
},
"InviteSalt": {
"type": "boolean"
},
"PasswordResetSalt": {
"type": "boolean"
},
"SendPushNotifications": {
"type": "boolean"
},
"PushNotificationServer": {
"type": "boolean"
},
"PushNotificationContents": {
"type": "boolean"
},
"EnableEmailBatching": {
"type": "boolean"
},
"EmailBatchingBufferSize": {
"type": "boolean"
},
"EmailBatchingInterval": {
"type": "boolean"
}
}
},
"RateLimitSettings": {
"type": "object",
"properties": {
"Enable": {
"type": "boolean"
},
"PerSec": {
"type": "boolean"
},
"MaxBurst": {
"type": "boolean"
},
"MemoryStoreSize": {
"type": "boolean"
},
"VaryByRemoteAddr": {
"type": "boolean"
},
"VaryByHeader": {
"type": "boolean"
}
}
},
"PrivacySettings": {
"type": "object",
"properties": {
"ShowEmailAddress": {
"type": "boolean"
},
"ShowFullName": {
"type": "boolean"
}
}
},
"SupportSettings": {
"type": "object",
"properties": {
"TermsOfServiceLink": {
"type": "boolean"
},
"PrivacyPolicyLink": {
"type": "boolean"
},
"AboutLink": {
"type": "boolean"
},
"HelpLink": {
"type": "boolean"
},
"ReportAProblemLink": {
"type": "boolean"
},
"SupportEmail": {
"type": "boolean"
}
}
},
"GitLabSettings": {
"type": "object",
"properties": {
"Enable": {
"type": "boolean"
},
"Secret": {
"type": "boolean"
},
"Id": {
"type": "boolean"
},
"Scope": {
"type": "boolean"
},
"AuthEndpoint": {
"type": "boolean"
},
"TokenEndpoint": {
"type": "boolean"
},
"UserApiEndpoint": {
"type": "boolean"
}
}
},
"GoogleSettings": {
"type": "object",
"properties": {
"Enable": {
"type": "boolean"
},
"Secret": {
"type": "boolean"
},
"Id": {
"type": "boolean"
},
"Scope": {
"type": "boolean"
},
"AuthEndpoint": {
"type": "boolean"
},
"TokenEndpoint": {
"type": "boolean"
},
"UserApiEndpoint": {
"type": "boolean"
}
}
},
"Office365Settings": {
"type": "object",
"properties": {
"Enable": {
"type": "boolean"
},
"Secret": {
"type": "boolean"
},
"Id": {
"type": "boolean"
},
"Scope": {
"type": "boolean"
},
"AuthEndpoint": {
"type": "boolean"
},
"TokenEndpoint": {
"type": "boolean"
},
"UserApiEndpoint": {
"type": "boolean"
}
}
},
"LdapSettings": {
"type": "object",
"properties": {
"Enable": {
"type": "boolean"
},
"LdapServer": {
"type": "boolean"
},
"LdapPort": {
"type": "boolean"
},
"ConnectionSecurity": {
"type": "boolean"
},
"BaseDN": {
"type": "boolean"
},
"BindUsername": {
"type": "boolean"
},
"BindPassword": {
"type": "boolean"
},
"UserFilter": {
"type": "boolean"
},
"FirstNameAttribute": {
"type": "boolean"
},
"LastNameAttribute": {
"type": "boolean"
},
"EmailAttribute": {
"type": "boolean"
},
"UsernameAttribute": {
"type": "boolean"
},
"NicknameAttribute": {
"type": "boolean"
},
"IdAttribute": {
"type": "boolean"
},
"PositionAttribute": {
"type": "boolean"
},
"SyncIntervalMinutes": {
"type": "boolean"
},
"SkipCertificateVerification": {
"type": "boolean"
},
"QueryTimeout": {
"type": "boolean"
},
"MaxPageSize": {
"type": "boolean"
},
"LoginFieldName": {
"type": "boolean"
}
}
},
"ComplianceSettings": {
"type": "object",
"properties": {
"Enable": {
"type": "boolean"
},
"Directory": {
"type": "boolean"
},
"EnableDaily": {
"type": "boolean"
}
}
},
"LocalizationSettings": {
"type": "object",
"properties": {
"DefaultServerLocale": {
"type": "boolean"
},
"DefaultClientLocale": {
"type": "boolean"
},
"AvailableLocales": {
"type": "boolean"
}
}
},
"SamlSettings": {
"type": "object",
"properties": {
"Enable": {
"type": "boolean"
},
"Verify": {
"type": "boolean"
},
"Encrypt": {
"type": "boolean"
},
"IdpUrl": {
"type": "boolean"
},
"IdpDescriptorUrl": {
"type": "boolean"
},
"AssertionConsumerServiceURL": {
"type": "boolean"
},
"IdpCertificateFile": {
"type": "boolean"
},
"PublicCertificateFile": {
"type": "boolean"
},
"PrivateKeyFile": {
"type": "boolean"
},
"FirstNameAttribute": {
"type": "boolean"
},
"LastNameAttribute": {
"type": "boolean"
},
"EmailAttribute": {
"type": "boolean"
},
"UsernameAttribute": {
"type": "boolean"
},
"NicknameAttribute": {
"type": "boolean"
},
"LocaleAttribute": {
"type": "boolean"
},
"PositionAttribute": {
"type": "boolean"
},
"LoginButtonText": {
"type": "boolean"
}
}
},
"NativeAppSettings": {
"type": "object",
"properties": {
"AppDownloadLink": {
"type": "boolean"
},
"AndroidAppDownloadLink": {
"type": "boolean"
},
"IosAppDownloadLink": {
"type": "boolean"
}
}
},
"ClusterSettings": {
"type": "object",
"properties": {
"Enable": {
"type": "boolean"
},
"InterNodeListenAddress": {
"type": "boolean"
},
"InterNodeUrls": {
"type": "boolean"
}
}
},
"MetricsSettings": {
"type": "object",
"properties": {
"Enable": {
"type": "boolean"
},
"BlockProfileRate": {
"type": "boolean"
},
"ListenAddress": {
"type": "boolean"
}
}
},
"AnalyticsSettings": {
"type": "object",
"properties": {
"MaxUsersForStatistics": {
"type": "boolean"
}
}
}
}
},
"SamlCertificateStatus": {
"type": "object",
"properties": {
"idp_certificate_file": {
"description": "Status is good when `true`",
"type": "boolean"
},
"public_certificate_file": {
"description": "Status is good when `true`",
"type": "boolean"
},
"private_key_file": {
"description": "Status is good when `true`",
"type": "boolean"
}
}
},
"Compliance": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"create_at": {
"type": "integer",
"format": "int64"
},
"user_id": {
"type": "string"
},
"status": {
"type": "string"
},
"count": {
"type": "integer"
},
"desc": {
"type": "string"
},
"type": {
"type": "string"
},
"start_at": {
"type": "integer",
"format": "int64"
},
"end_at": {
"type": "integer",
"format": "int64"
},
"keywords": {
"type": "string"
},
"emails": {
"type": "string"
}
}
},
"ClusterInfo": {
"type": "object",
"properties": {
"id": {
"description": "The unique ID for the node",
"type": "string"
},
"version": {
"description": "The server version the node is on",
"type": "string"
},
"config_hash": {
"description": "The hash of the configuartion file the node is using",
"type": "string"
},
"internode_url": {
"description": "The URL used to communicate with those node from other nodes",
"type": "string"
},
"hostname": {
"description": "The hostname for this node",
"type": "string"
},
"last_ping": {
"description": "The time of the last ping to this node",
"type": "integer"
},
"is_alive": {
"description": "Whether or not the node is alive and well",
"type": "boolean"
}
}
},
"AppError": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
},
"Status": {
"type": "object",
"properties": {
"user_id": {
"type": "string"
},
"status": {
"type": "string"
},
"manual": {
"type": "boolean"
},
"last_activity_at": {
"type": "integer",
"format": "int64"
}
}
},
"OAuthApp": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The client id of the application"
},
"client_secret": {
"type": "string",
"description": "The client secret of the application"
},
"name": {
"type": "string",
"description": "The name of the client application"
},
"description": {
"type": "string",
"description": "A short description of the application"
},
"icon_url": {
"type": "string",
"description": "A URL to an icon to display with the application"
},
"callback_urls": {
"type": "array",
"items": {
"type": "string"
},
"description": "A list of callback URLs for the appliation"
},
"homepage": {
"type": "string",
"description": "A link to the website of the application"
},
"is_trusted": {
"type": "boolean",
"description": "Set this to `true` to skip asking users for permission"
},
"create_at": {
"type": "integer",
"description": "The time of registration for the application",
"format": "int64"
},
"update_at": {
"type": "integer",
"description": "The last time of update for the application",
"format": "int64"
}
}
},
"Job": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The unique id of the job"
},
"type": {
"type": "string",
"description": "The type of job"
},
"create_at": {
"type": "integer",
"description": "The time at which the job was created",
"format": "int64"
},
"start_at": {
"type": "integer",
"description": "The time at which the job was started",
"format": "int64"
},
"last_activity_at": {
"type": "integer",
"description": "The last time at which the job had activity",
"format": "int64"
},
"status": {
"type": "string",
"description": "The status of the job"
},
"progress": {
"type": "integer",
"description": "The progress (as a percentage) of the job"
},
"data": {
"type": "object",
"description": "A freeform data field containing additional information about the job"
}
}
},
"UserAccessToken": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the token"
},
"token": {
"type": "string",
"description": "The token used for authentication"
},
"user_id": {
"type": "string",
"description": "The user the token authenticates for"
},
"description": {
"type": "string",
"description": "A description of the token usage"
}
}
},
"UserAccessTokenSanitized": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the token"
},
"user_id": {
"type": "string",
"description": "The user the token authenticates for"
},
"description": {
"type": "string",
"description": "A description of the token usage"
},
"is_active": {
"type": "boolean",
"description": "Indicates whether the token is active"
}
}
},
"GlobalDataRetentionPolicy": {
"type": "object",
"properties": {
"message_deletion_enabled": {
"type": "boolean",
"description": "Indicates whether data retention policy deletion of messages is enabled globally."
},
"file_deletion_enabled": {
"type": "boolean",
"description": "Indicates whether data retention policy deletion of file attachments is enabled globally."
},
"message_retention_cutoff": {
"type": "integer",
"description": "The current server timestamp before which messages should be deleted."
},
"file_retention_cutoff": {
"type": "integer",
"description": "The current server timestamp before which files should be deleted."
}
}
},
"DataRetentionPolicyWithoutId": {
"type": "object",
"properties": {
"display_name": {
"type": "string",
"description": "The display name for this retention policy."
},
"post_duration": {
"type": "integer",
"description": "The number of days a message will be retained before being deleted by this policy. If this value is less than 0, the policy has infinite retention (i.e. messages are never deleted).\n"
}
}
},
"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": "boolean",
"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": "boolean",
"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": "boolean",
"description": "Set to \"true\" to enable channel-wide notifications (@channel, @all, etc.), \"false\" to disable. Defaults to \"true\"."
},
"first_name": {
"type": "boolean",
"description": "Set to \"true\" to enable mentions for first name. Defaults to \"true\" if a first name is set, \"false\" otherwise."
}
}
},
"Timezone": {
"type": "object",
"properties": {
"useAutomaticTimezone": {
"type": "boolean",
"description": "Set to \"true\" to use the browser/system timezone, \"false\" to set manually. Defaults to \"true\"."
},
"manualTimezone": {
"type": "string",
"description": "Value when setting manually the timezone, i.e. \"Europe/Berlin\"."
},
"automaticTimezone": {
"type": "string",
"description": "This value is set automatically when the \"useAutomaticTimezone\" is set to \"true\"."
}
}
},
"ChannelNotifyProps": {
"type": "object",
"properties": {
"email": {
"type": "boolean",
"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.\n\nAvailable as server version 5.6.\n"
},
"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"
}
}
},
"PaymentSetupIntent": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"client_secret": {
"type": "string"
}
}
},
"PaymentMethod": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"last_four": {
"type": "integer"
},
"exp_month": {
"type": "integer"
},
"exp_year": {
"type": "integer"
},
"card_brand": {
"type": "string"
},
"name": {
"type": "string"
}
}
},
"Address": {
"type": "object",
"properties": {
"city": {
"type": "string"
},
"country": {
"type": "string"
},
"line1": {
"type": "string"
},
"line2": {
"type": "string"
},
"postal_code": {
"type": "string"
},
"state": {
"type": "string"
}
}
},
"CloudCustomer": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"creator_id": {
"type": "string"
},
"create_at": {
"type": "integer",
"format": "int64"
},
"email": {
"type": "string"
},
"name": {
"type": "string"
},
"num_employees": {
"type": "string"
},
"contact_first_name": {
"type": "string"
},
"contact_last_name": {
"type": "string"
},
"billing_address": {
"$ref": "#/components/schemas/Address"
},
"company_address": {
"$ref": "#/components/schemas/Address"
},
"payment_method": {
"$ref": "#/components/schemas/PaymentMethod"
}
}
},
"Subscription": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"customer_id": {
"type": "string"
},
"product_id": {
"type": "string"
},
"add_ons": {
"type": "array",
"items": {
"type": "string"
}
},
"start_at": {
"type": "integer",
"format": "int64"
},
"end_at": {
"type": "integer",
"format": "int64"
},
"create_at": {
"type": "integer",
"format": "int64"
},
"seats": {
"type": "integer"
},
"dns": {
"type": "string"
}
}
},
"SubscriptionStats": {
"type": "object",
"properties": {
"remaining_seats": {
"type": "integer"
},
"is_paid_tier": {
"type": "string"
}
}
},
"Invoice": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"number": {
"type": "string"
},
"create_at": {
"type": "integer",
"format": "int64"
},
"total": {
"type": "integer",
"format": "int64"
},
"tax": {
"type": "integer",
"format": "int64"
},
"status": {
"type": "string"
},
"period_start": {
"type": "integer",
"format": "int64"
},
"period_end": {
"type": "integer",
"format": "int64"
},
"subscription_id": {
"type": "string"
},
"item": {
"type": "array",
"items": {
"$ref": "#/components/schemas/InvoiceLineItem"
}
}
}
},
"InvoiceLineItem": {
"type": "object",
"properties": {
"price_id": {
"type": "string"
},
"total": {
"type": "integer",
"format": "int64"
},
"quantity": {
"type": "integer",
"format": "int64"
},
"price_per_unit": {
"type": "integer",
"format": "int64"
},
"description": {
"type": "string"
},
"metadata": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"Group": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"display_name": {
"type": "string"
},
"description": {
"type": "string"
},
"source": {
"type": "string"
},
"remote_id": {
"type": "string"
},
"create_at": {
"type": "integer",
"format": "int64"
},
"update_at": {
"type": "integer",
"format": "int64"
},
"delete_at": {
"type": "integer",
"format": "int64"
},
"has_syncables": {
"type": "boolean"
}
}
},
"GroupSyncableTeam": {
"type": "object",
"properties": {
"team_id": {
"type": "string"
},
"group_id": {
"type": "string"
},
"auto_add": {
"type": "boolean"
},
"create_at": {
"type": "integer",
"format": "int64"
},
"delete_at": {
"type": "integer",
"format": "int64"
},
"update_at": {
"type": "integer",
"format": "int64"
}
}
},
"GroupSyncableChannel": {
"type": "object",
"properties": {
"channel_id": {
"type": "string"
},
"group_id": {
"type": "string"
},
"auto_add": {
"type": "boolean"
},
"create_at": {
"type": "integer",
"format": "int64"
},
"delete_at": {
"type": "integer",
"format": "int64"
},
"update_at": {
"type": "integer",
"format": "int64"
}
}
},
"GroupSyncableTeams": {
"type": "object",
"properties": {
"team_id": {
"type": "string"
},
"team_display_name": {
"type": "string"
},
"team_type": {
"type": "string"
},
"group_id": {
"type": "string"
},
"auto_add": {
"type": "boolean"
},
"create_at": {
"type": "integer",
"format": "int64"
},
"delete_at": {
"type": "integer",
"format": "int64"
},
"update_at": {
"type": "integer",
"format": "int64"
}
}
},
"GroupSyncableChannels": {
"type": "object",
"properties": {
"channel_id": {
"type": "string"
},
"channel_display_name": {
"type": "string"
},
"channel_type": {
"type": "string"
},
"team_id": {
"type": "string"
},
"team_display_name": {
"type": "string"
},
"team_type": {
"type": "string"
},
"group_id": {
"type": "string"
},
"auto_add": {
"type": "boolean"
},
"create_at": {
"type": "integer",
"format": "int64"
},
"delete_at": {
"type": "integer",
"format": "int64"
},
"update_at": {
"type": "integer",
"format": "int64"
}
}
},
"ChannelModeration": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"roles": {
"$ref": "#/components/schemas/ChannelModeratedRoles"
}
}
},
"ChannelModeratedRoles": {
"type": "object",
"properties": {
"guests": {
"$ref": "#/components/schemas/ChannelModeratedRole"
},
"members": {
"$ref": "#/components/schemas/ChannelModeratedRole"
}
}
},
"ChannelModeratedRole": {
"type": "object",
"properties": {
"value": {
"type": "boolean"
},
"enabled": {
"type": "boolean"
}
}
},
"ChannelModeratedRolesPatch": {
"type": "object",
"properties": {
"guests": {
"type": "boolean"
},
"members": {
"type": "boolean"
}
}
},
"ChannelModerationPatch": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"roles": {
"$ref": "#/components/schemas/ChannelModeratedRolesPatch"
}
}
},
"ChannelMemberCountByGroup": {
"description": "An object describing group member information in a channel",
"type": "object",
"properties": {
"group_id": {
"type": "string",
"description": "ID of the group"
},
"channel_member_count": {
"type": "number",
"description": "Total number of group members in the channel"
},
"channel_member_timezones_count": {
"type": "number",
"description": "Total number of unique timezones for the group members in the channel"
}
}
},
"LDAPGroupsPaged": {
"description": "A paged list of LDAP groups",
"type": "object",
"properties": {
"count": {
"type": "number",
"description": "Total number of groups"
},
"groups": {
"type": "array",
"items": {
"$ref": "#/components/schemas/LDAPGroup"
}
}
}
},
"LDAPGroup": {
"description": "A LDAP group",
"type": "object",
"properties": {
"has_syncables": {
"type": "boolean"
},
"mattermost_group_id": {
"type": "string"
},
"primary_key": {
"type": "string"
},
"name": {
"type": "string"
}
}
},
"SidebarCategory": {
"description": "User's sidebar category",
"type": "object",
"properties": {
"id": {
"type": "string"
},
"user_id": {
"type": "string"
},
"team_id": {
"type": "string"
},
"display_name": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"channels",
"custom",
"direct_messages",
"favorites"
]
}
}
},
"SidebarCategoryWithChannels": {
"description": "User's sidebar category with it's channels",
"type": "object",
"properties": {
"id": {
"type": "string"
},
"user_id": {
"type": "string"
},
"team_id": {
"type": "string"
},
"display_name": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"channels",
"custom",
"direct_messages",
"favorites"
]
},
"channel_ids": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"OrderedSidebarCategories": {
"description": "List of user's categories with their channels",
"type": "object",
"properties": {
"order": {
"type": "array",
"items": {
"type": "string"
}
},
"categories": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SidebarCategoryWithChannels"
}
}
}
},
"Bot": {
"description": "A bot account",
"type": "object",
"properties": {
"user_id": {
"description": "The user id of the associated user entry.",
"type": "string"
},
"create_at": {
"description": "The time in milliseconds a bot was created",
"type": "integer",
"format": "int64"
},
"update_at": {
"description": "The time in milliseconds a bot was last updated",
"type": "integer",
"format": "int64"
},
"delete_at": {
"description": "The time in milliseconds a bot was deleted",
"type": "integer",
"format": "int64"
},
"username": {
"type": "string"
},
"display_name": {
"type": "string"
},
"description": {
"type": "string"
},
"owner_id": {
"description": "The user id of the user that currently owns this bot.",
"type": "string"
}
}
},
"Server_Busy": {
"type": "object",
"properties": {
"busy": {
"description": "True if the server is marked as busy (under high load)",
"type": "boolean"
},
"expires": {
"description": "timestamp - number of seconds since Jan 1, 1970 UTC.",
"type": "integer",
"format": "int64"
}
}
},
"GroupWithSchemeAdmin": {
"description": "group augmented with scheme admin information",
"type": "object",
"properties": {
"group": {
"$ref": "#/components/schemas/Group"
},
"scheme_admin": {
"type": "boolean"
}
}
},
"GroupsAssociatedToChannels": {
"description": "a map of channel id(s) to the set of groups that constrain the corresponding channel in a team",
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"$ref": "#/components/schemas/GroupWithSchemeAdmin"
}
}
},
"OrphanedRecord": {
"description": "an object containing information about an orphaned record.",
"type": "object",
"properties": {
"parent_id": {
"type": "string",
"description": "the id of the parent relation (table) entry."
},
"child_id": {
"type": "string",
"description": "the id of the child relation (table) entry."
}
}
},
"UserThread": {
"description": "a thread that user is following",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "ID of the post that is this thread's root"
},
"reply_count": {
"type": "integer",
"description": "number of replies in this thread"
},
"last_reply_at": {
"type": "integer",
"format": "int64",
"description": "timestamp of the last post to this thread"
},
"last_viewed_at": {
"type": "integer",
"format": "int64",
"description": "timestamp of the last time the user viewed this thread"
},
"participants": {
"type": "array",
"description": "list of users participating in this thread. only includes IDs unless 'extended' was set to 'true'",
"items": {
"$ref": "#/components/schemas/Post"
}
},
"post": {
"$ref": "#/components/schemas/Post"
}
}
},
"RelationalIntegrityCheckData": {
"description": "an object containing the results of a relational integrity check.",
"type": "object",
"properties": {
"parent_name": {
"type": "string",
"description": "the name of the parent relation (table)."
},
"child_name": {
"type": "string",
"description": "the name of the child relation (table)."
},
"parent_id_attr": {
"type": "string",
"description": "the name of the attribute (column) containing the parent id."
},
"child_id_attr": {
"type": "string",
"description": "the name of the attribute (column) containing the child id."
},
"records": {
"description": "the list of orphaned records found.",
"type": "array",
"items": {
"$ref": "#/components/schemas/OrphanedRecord"
}
}
}
},
"IntegrityCheckResult": {
"description": "an object with the result of the integrity check.",
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/RelationalIntegrityCheckData"
},
"err": {
"type": "string",
"description": "a string value set in case of error."
}
}
},
"UploadSession": {
"description": "an object containing information used to keep track of a file upload.",
"type": "object",
"properties": {
"id": {
"description": "The unique identifier for the upload.",
"type": "string"
},
"type": {
"description": "The type of the upload.",
"type": "string",
"enum": [
"attachment",
"import"
]
},
"create_at": {
"description": "The time the upload was created in milliseconds.",
"type": "integer",
"format": "int64"
},
"user_id": {
"description": "The ID of the user performing the upload.",
"type": "string"
},
"channel_id": {
"description": "The ID of the channel to upload to.",
"type": "string"
},
"filename": {
"description": "The name of the file to upload.",
"type": "string"
},
"file_size": {
"description": "The size of the file to upload in bytes.",
"type": "integer",
"format": "int64"
},
"file_offset": {
"description": "The amount of data uploaded in bytes.",
"type": "integer",
"format": "int64"
}
}
},
"Notice": {
"type": "object",
"properties": {
"id": {
"description": "Notice ID",
"type": "string"
},
"sysAdminOnly": {
"description": "Does this notice apply only to sysadmins",
"type": "boolean"
},
"teamAdminOnly": {
"description": "Does this notice apply only to team admins",
"type": "boolean"
},
"action": {
"description": "Optional action to perform on action button click. (defaults to closing the notice)",
"type": "string"
},
"actionParam": {
"description": "Optional action parameter. \nExample: {\"action\": \"url\", actionParam: \"/console/some-page\"}",
"type": "string"
},
"actionText": {
"description": "Optional override for the action button text (defaults to OK)",
"type": "string"
},
"description": {
"description": "Notice content. Use {{Mattermost}} instead of plain text to support white-labeling. Text supports Markdown.",
"type": "string"
},
"image": {
"description": "URL of image to display",
"type": "string"
},
"title": {
"description": "Notice title. Use {{Mattermost}} instead of plain text to support white-labeling. Text supports Markdown.",
"type": "string"
}
}
},
"SharedChannel": {
"type": "object",
"properties": {
"id": {
"description": "Channel id of the shared channel",
"type": "string"
},
"team_id": {
"type": "string"
},
"home": {
"description": "Is this the home cluster for the shared channel",
"type": "boolean"
},
"readonly": {
"description": "Is this shared channel shared as read only",
"type": "boolean"
},
"name": {
"description": "Channel name as it is shared (may be different than original channel name)",
"type": "string"
},
"display_name": {
"description": "Channel display name as it appears locally",
"type": "string"
},
"purpose": {
"type": "string"
},
"header": {
"type": "string"
},
"creator_id": {
"description": "Id of the user that shared the channel",
"type": "string"
},
"create_at": {
"description": "Time in milliseconds that the channel was shared",
"type": "integer"
},
"update_at": {
"description": "Time in milliseconds that the shared channel record was last updated",
"type": "integer"
},
"remote_id": {
"description": "Id of the remote cluster where the shared channel is homed",
"type": "string"
}
}
},
"RemoteClusterInfo": {
"type": "object",
"properties": {
"display_name": {
"description": "The display name for the remote cluster",
"type": "string"
},
"create_at": {
"description": "The time in milliseconds a remote cluster was created",
"type": "integer",
"format": "int64"
},
"last_ping_at": {
"description": "The time in milliseconds a remote cluster was last pinged successfully",
"type": "integer",
"format": "int64"
}
}
},
"SystemStatusResponse": {
"type": "object",
"properties": {
"AndroidLatestVersion": {
"description": "Latest Android version supported",
"type": "string"
},
"AndroidMinVersion": {
"description": "Minimum Android version supported",
"type": "string"
},
"DesktopLatestVersion": {
"description": "Latest desktop version supported",
"type": "string"
},
"DesktopMinVersion": {
"description": "Minimum desktop version supported",
"type": "string"
},
"IosLatestVersion": {
"description": "Latest iOS version supported",
"type": "string"
},
"IosMinVersion": {
"description": "Minimum iOS version supported",
"type": "string"
},
"database_status": {
"description": "Status of database (\"OK\" or \"UNHEALTHY\"). Included when get_server_status parameter set.",
"type": "string"
},
"filestore_status": {
"description": "Status of filestore (\"OK\" or \"UNHEALTHY\"). Included when get_server_status parameter set.",
"type": "string"
},
"status": {
"description": "Status of server (\"OK\" or \"UNHEALTHY\"). Included when get_server_status parameter set.",
"type": "string"
}
}
},
"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"
}
}
}
}
},
"externalDocs": {
"description": "Find out more about Mattermost",
"url": "https://about.mattermost.com"
},
"security": [
{
"bearerAuth": []
}
]
}