swagger.json

{
  "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"
                }