Skip to content

Instantly share code, notes, and snippets.

@acunniffe

acunniffe/mattermost-dereffed-oas.json

Created May 5, 2019 22:37
Show Gist options
  • Save acunniffe/7466b5d313b40259f9844a0fb4bb3097 to your computer and use it in GitHub Desktop.
Save acunniffe/7466b5d313b40259f9844a0fb4bb3097 to your computer and use it in GitHub Desktop.
Download ZIP
Mattermost OAS Dereffed
Raw
mattermost-dereffed-oas.json
{
"swagger": "2.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": "[email protected]"
},
"x-logo": {
"url": "https://www.mattermost.org/wp-content/uploads/2016/03/logoHorizontal_WS.png",
"backgroundColor": "#FFFFFF"
}
},
"basePath": "/api/v4",
"host": "your-mattermost-url.com",
"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.js)\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\":\"[email protected]\",\"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\\\":\\\"[email protected]\\\",\\\"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 from the webhook:\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}\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- 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\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.js).\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": "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": "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 interating 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": "dataretention",
"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": "terms of service",
"description": "Endpoints for getting and updating custom terms of service."
}
],
"x-tagGroups": [
{
"name": "Introduction",
"tags": [
"introduction",
"schema",
"APIv3 Deprecation"
]
},
{
"name": "Standard Features",
"tags": [
"drivers",
"authentication",
"errors",
"rate limiting",
"WebSocket"
]
},
{
"name": "Endpoints",
"tags": [
"users",
"teams",
"channels",
"posts",
"files",
"preferences",
"status",
"emoji",
"reactions",
"webhooks",
"commands",
"OpenGraph",
"system",
"brand",
"OAuth",
"SAML",
"LDAP",
"groups",
"compliance",
"cluster",
"elasticsearch",
"dataretention",
"jobs",
"plugins",
"roles",
"schemes",
"integration_actions",
"terms of service"
]
}
],
"schemes": [
"http",
"https"
],
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"responses": {
"Forbidden": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"Unauthorized": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"BadRequest": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"NotFound": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"TooLarge": {
"description": "Content too large",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"NotImplemented": {
"description": "Feature is disabled",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"InternalServerError": {
"description": "Something went wrong with the server",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"paths": {
"/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",
"parameters": [
{
"name": "t",
"in": "query",
"description": "Token id from an email invitation",
"required": false,
"type": "string"
},
{
"name": "iid",
"in": "query",
"description": "Token id from an invitation link",
"required": false,
"type": "string"
},
{
"in": "body",
"name": "body",
"description": "User object to be created",
"required": true,
"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": {
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Set to \"true\" to enable email notifications, \"false\" to disable. Defaults to \"true\"."
},
"push": {
"type": "string",
"description": "Set to \"all\" to receive push notifications for all activity, \"mention\" for mentions and direct messages only, and \"none\" to disable. Defaults to \"mention\"."
},
"desktop": {
"type": "string",
"description": "Set to \"all\" to receive desktop notifications for all activity, \"mention\" for mentions and direct messages only, and \"none\" to disable. Defaults to \"all\"."
},
"desktop_sound": {
"type": "string",
"description": "Set to \"true\" to enable sound on desktop notifications, \"false\" to disable. Defaults to \"true\"."
},
"mention_keys": {
"type": "string",
"description": "A comma-separated list of words to count as mentions. Defaults to username and @username."
},
"channel": {
"type": "string",
"description": "Set to \"true\" to enable channel-wide notifications (@channel, @all, etc.), \"false\" to disable. Defaults to \"true\"."
},
"first_name": {
"type": "string",
"description": "Set to \"true\" to enable mentions for first name. Defaults to \"true\" if a first name is set, \"false\" otherwise."
}
}
}
}
}
}
],
"responses": {
"201": {
"description": "User creation successful",
"schema": {
"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": {
"description": "Field only visible to self and admins",
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Set to \"true\" to enable email notifications, \"false\" to disable. Defaults to \"true\"."
},
"push": {
"type": "string",
"description": "Set to \"all\" to receive push notifications for all activity, \"mention\" for mentions and direct messages only, and \"none\" to disable. Defaults to \"mention\"."
},
"desktop": {
"type": "string",
"description": "Set to \"all\" to receive desktop notifications for all activity, \"mention\" for mentions and direct messages only, and \"none\" to disable. Defaults to \"all\"."
},
"desktop_sound": {
"type": "string",
"description": "Set to \"true\" to enable sound on desktop notifications, \"false\" to disable. Defaults to \"true\"."
},
"mention_keys": {
"type": "string",
"description": "A comma-separated list of words to count as mentions. Defaults to username and @username."
},
"channel": {
"type": "string",
"description": "Set to \"true\" to enable channel-wide notifications (@channel, @all, etc.), \"false\" to disable. Defaults to \"true\"."
},
"first_name": {
"type": "string",
"description": "Set to \"true\" to enable mentions for first name. Defaults to \"true\" if a first name is set, \"false\" otherwise."
}
}
},
"props": {
"type": "object"
},
"last_password_update": {
"type": "integer"
},
"last_picture_update": {
"type": "integer"
},
"failed_attempts": {
"type": "integer"
},
"mfa_active": {
"type": "boolean"
},
"timezone": {
"type": "object",
"properties": {
"useAutomaticTimezone": {
"type": "string",
"description": "Set to \"true\" to use the browser/system timezone, \"false\" to set manually. Defaults to \"true\"."
},
"manualTimezone": {
"type": "string",
"description": "Value when setting manually the timezone, i.e. \"Europe/Berlin\"."
},
"automaticTimezone": {
"type": "string",
"description": "This value is set automatically when the \"useAutomaticTimezone\" is set to \"true\"."
}
}
},
"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"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\n\nuser := &model.User{\n Username: \"username\",\n Email: \"[email protected]\",\n Password: \"Password1\",\n}\n\ncreatedUser, response := Client.CreateUser(user)\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",
"parameters": [
{
"name": "page",
"in": "query",
"description": "The page to select.",
"default": "0",
"type": "string"
},
{
"name": "per_page",
"in": "query",
"description": "The number of users per page. There is a maximum limit of 200 users per page.",
"default": "60",
"type": "string"
},
{
"name": "in_team",
"in": "query",
"description": "The ID of the team to get users for.",
"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.",
"type": "string"
},
{
"name": "in_channel",
"in": "query",
"description": "The ID of the channel to get users for.",
"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.",
"type": "string"
},
{
"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`.",
"type": "boolean"
},
{
"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",
"type": "string"
}
],
"responses": {
"200": {
"description": "User page retrieval successful",
"schema": {
"type": "array",
"items": {
"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": {
"description": "Field only visible to self and admins",
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Set to \"true\" to enable email notifications, \"false\" to disable. Defaults to \"true\"."
},
"push": {
"type": "string",
"description": "Set to \"all\" to receive push notifications for all activity, \"mention\" for mentions and direct messages only, and \"none\" to disable. Defaults to \"mention\"."
},
"desktop": {
"type": "string",
"description": "Set to \"all\" to receive desktop notifications for all activity, \"mention\" for mentions and direct messages only, and \"none\" to disable. Defaults to \"all\"."
},
"desktop_sound": {
"type": "string",
"description": "Set to \"true\" to enable sound on desktop notifications, \"false\" to disable. Defaults to \"true\"."
},
"mention_keys": {
"type": "string",
"description": "A comma-separated list of words to count as mentions. Defaults to username and @username."
},
"channel": {
"type": "string",
"description": "Set to \"true\" to enable channel-wide notifications (@channel, @all, etc.), \"false\" to disable. Defaults to \"true\"."
},
"first_name": {
"type": "string",
"description": "Set to \"true\" to enable mentions for first name. Defaults to \"true\" if a first name is set, \"false\" otherwise."
}
}
},
"props": {
"type": "object"
},
"last_password_update": {
"type": "integer"
},
"last_picture_update": {
"type": "integer"
},
"failed_attempts": {
"type": "integer"
},
"mfa_active": {
"type": "boolean"
},
"timezone": {
"type": "object",
"properties": {
"useAutomaticTimezone": {
"type": "string",
"description": "Set to \"true\" to use the browser/system timezone, \"false\" to set manually. Defaults to \"true\"."
},
"manualTimezone": {
"type": "string",
"description": "Value when setting manually the timezone, i.e. \"Europe/Berlin\"."
},
"automaticTimezone": {
"type": "string",
"description": "This value is set automatically when the \"useAutomaticTimezone\" is set to \"true\"."
}
}
},
"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"
}
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"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"
}
]
}
},
"/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",
"parameters": [
{
"in": "body",
"name": "body",
"description": "List of user ids",
"required": true,
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
}
],
"responses": {
"200": {
"description": "User list retrieval successful",
"schema": {
"type": "array",
"items": {
"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": {
"description": "Field only visible to self and admins",
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Set to \"true\" to enable email notifications, \"false\" to disable. Defaults to \"true\"."
},
"push": {
"type": "string",
"description": "Set to \"all\" to receive push notifications for all activity, \"mention\" for mentions and direct messages only, and \"none\" to disable. Defaults to \"mention\"."
},
"desktop": {
"type": "string",
"description": "Set to \"all\" to receive desktop notifications for all activity, \"mention\" for mentions and direct messages only, and \"none\" to disable. Defaults to \"all\"."
},
"desktop_sound": {
"type": "string",
"description": "Set to \"true\" to enable sound on desktop notifications, \"false\" to disable. Defaults to \"true\"."
},
"mention_keys": {
"type": "string",
"description": "A comma-separated list of words to count as mentions. Defaults to username and @username."
},
"channel": {
"type": "string",
"description": "Set to \"true\" to enable channel-wide notifications (@channel, @all, etc.), \"false\" to disable. Defaults to \"true\"."
},
"first_name": {
"type": "string",
"description": "Set to \"true\" to enable mentions for first name. Defaults to \"true\" if a first name is set, \"false\" otherwise."
}
}
},
"props": {
"type": "object"
},
"last_password_update": {
"type": "integer"
},
"last_picture_update": {
"type": "integer"
},
"failed_attempts": {
"type": "integer"
},
"mfa_active": {
"type": "boolean"
},
"timezone": {
"type": "object",
"properties": {
"useAutomaticTimezone": {
"type": "string",
"description": "Set to \"true\" to use the browser/system timezone, \"false\" to set manually. Defaults to \"true\"."
},
"manualTimezone": {
"type": "string",
"description": "Value when setting manually the timezone, i.e. \"Europe/Berlin\"."
},
"automaticTimezone": {
"type": "string",
"description": "This value is set automatically when the \"useAutomaticTimezone\" is set to \"true\"."
}
}
},
"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"
}
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
},
"/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",
"parameters": [
{
"in": "body",
"name": "body",
"description": "List of usernames",
"required": true,
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
}
],
"responses": {
"200": {
"description": "User list retrieval successful",
"schema": {
"type": "array",
"items": {
"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": {
"description": "Field only visible to self and admins",
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Set to \"true\" to enable email notifications, \"false\" to disable. Defaults to \"true\"."
},
"push": {
"type": "string",
"description": "Set to \"all\" to receive push notifications for all activity, \"mention\" for mentions and direct messages only, and \"none\" to disable. Defaults to \"mention\"."
},
"desktop": {
"type": "string",
"description": "Set to \"all\" to receive desktop notifications for all activity, \"mention\" for mentions and direct messages only, and \"none\" to disable. Defaults to \"all\"."
},
"desktop_sound": {
"type": "string",
"description": "Set to \"true\" to enable sound on desktop notifications, \"false\" to disable. Defaults to \"true\"."
},
"mention_keys": {
"type": "string",
"description": "A comma-separated list of words to count as mentions. Defaults to username and @username."
},
"channel": {
"type": "string",
"description": "Set to \"true\" to enable channel-wide notifications (@channel, @all, etc.), \"false\" to disable. Defaults to \"true\"."
},
"first_name": {
"type": "string",
"description": "Set to \"true\" to enable mentions for first name. Defaults to \"true\" if a first name is set, \"false\" otherwise."
}
}
},
"props": {
"type": "object"
},
"last_password_update": {
"type": "integer"
},
"last_picture_update": {
"type": "integer"
},
"failed_attempts": {
"type": "integer"
},
"mfa_active": {
"type": "boolean"
},
"timezone": {
"type": "object",
"properties": {
"useAutomaticTimezone": {
"type": "string",
"description": "Set to \"true\" to use the browser/system timezone, \"false\" to set manually. Defaults to \"true\"."
},
"manualTimezone": {
"type": "string",
"description": "Value when setting manually the timezone, i.e. \"Europe/Berlin\"."
},
"automaticTimezone": {
"type": "string",
"description": "This value is set automatically when the \"useAutomaticTimezone\" is set to \"true\"."
}
}
},
"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"
}
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"Password1\")\n\nusers, resp := Client.GetUsersByUsernames([]string{\"username1\", \"username2\"})\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",
"parameters": [
{
"in": "body",
"name": "body",
"description": "Search criteria",
"required": true,
"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"
},
"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
}
}
}
}
],
"responses": {
"200": {
"description": "User list retrieval successful",
"schema": {
"type": "array",
"items": {
"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": {
"description": "Field only visible to self and admins",
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Set to \"true\" to enable email notifications, \"false\" to disable. Defaults to \"true\"."
},
"push": {
"type": "string",
"description": "Set to \"all\" to receive push notifications for all activity, \"mention\" for mentions and direct messages only, and \"none\" to disable. Defaults to \"mention\"."
},
"desktop": {
"type": "string",
"description": "Set to \"all\" to receive desktop notifications for all activity, \"mention\" for mentions and direct messages only, and \"none\" to disable. Defaults to \"all\"."
},
"desktop_sound": {
"type": "string",
"description": "Set to \"true\" to enable sound on desktop notifications, \"false\" to disable. Defaults to \"true\"."
},
"mention_keys": {
"type": "string",
"description": "A comma-separated list of words to count as mentions. Defaults to username and @username."
},
"channel": {
"type": "string",
"description": "Set to \"true\" to enable channel-wide notifications (@channel, @all, etc.), \"false\" to disable. Defaults to \"true\"."
},
"first_name": {
"type": "string",
"description": "Set to \"true\" to enable mentions for first name. Defaults to \"true\" if a first name is set, \"false\" otherwise."
}
}
},
"props": {
"type": "object"
},
"last_password_update": {
"type": "integer"
},
"last_picture_update": {
"type": "integer"
},
"failed_attempts": {
"type": "integer"
},
"mfa_active": {
"type": "boolean"
},
"timezone": {
"type": "object",
"properties": {
"useAutomaticTimezone": {
"type": "string",
"description": "Set to \"true\" to use the browser/system timezone, \"false\" to set manually. Defaults to \"true\"."
},
"manualTimezone": {
"type": "string",
"description": "Value when setting manually the timezone, i.e. \"Europe/Berlin\"."
},
"automaticTimezone": {
"type": "string",
"description": "This value is set automatically when the \"useAutomaticTimezone\" is set to \"true\"."
}
}
},
"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"
}
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"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"
}
]
}
},
"/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",
"parameters": [
{
"name": "team_id",
"in": "query",
"description": "Team ID",
"type": "string"
},
{
"name": "channel_id",
"in": "query",
"description": "Channel ID",
"type": "string"
},
{
"name": "name",
"in": "query",
"description": "Username, nickname first name or last name",
"required": true,
"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",
"type": "integer",
"default": 100
}
],
"responses": {
"200": {
"description": "User autocomplete successful",
"schema": {
"type": "object",
"properties": {
"users": {
"description": "A list of users that are the main result of the query",
"type": "array",
"items": {
"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": {
"description": "Field only visible to self and admins",
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Set to \"true\" to enable email notifications, \"false\" to disable. Defaults to \"true\"."
},
"push": {
"type": "string",
"description": "Set to \"all\" to receive push notifications for all activity, \"mention\" for mentions and direct messages only, and \"none\" to disable. Defaults to \"mention\"."
},
"desktop": {
"type": "string",
"description": "Set to \"all\" to receive desktop notifications for all activity, \"mention\" for mentions and direct messages only, and \"none\" to disable. Defaults to \"all\"."
},
"desktop_sound": {
"type": "string",
"description": "Set to \"true\" to enable sound on desktop notifications, \"false\" to disable. Defaults to \"true\"."
},
"mention_keys": {
"type": "string",
"description": "A comma-separated list of words to count as mentions. Defaults to username and @username."
},
"channel": {
"type": "string",
"description": "Set to \"true\" to enable channel-wide notifications (@channel, @all, etc.), \"false\" to disable. Defaults to \"true\"."
},
"first_name": {
"type": "string",
"description": "Set to \"true\" to enable mentions for first name. Defaults to \"true\" if a first name is set, \"false\" otherwise."
}
}
},
"props": {
"type": "object"
},
"last_password_update": {
"type": "integer"
},
"last_picture_update": {
"type": "integer"
},
"failed_attempts": {
"type": "integer"
},
"mfa_active": {
"type": "boolean"
},
"timezone": {
"type": "object",
"properties": {
"useAutomaticTimezone": {
"type": "string",
"description": "Set to \"true\" to use the browser/system timezone, \"false\" to set manually. Defaults to \"true\"."
},
"manualTimezone": {
"type": "string",
"description": "Value when setting manually the timezone, i.e. \"Europe/Berlin\"."
},
"automaticTimezone": {
"type": "string",
"description": "This value is set automatically when the \"useAutomaticTimezone\" is set to \"true\"."
}
}
},
"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"
}
}
}
},
"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": {
"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": {
"description": "Field only visible to self and admins",
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Set to \"true\" to enable email notifications, \"false\" to disable. Defaults to \"true\"."
},
"push": {
"type": "string",
"description": "Set to \"all\" to receive push notifications for all activity, \"mention\" for mentions and direct messages only, and \"none\" to disable. Defaults to \"mention\"."
},
"desktop": {
"type": "string",
"description": "Set to \"all\" to receive desktop notifications for all activity, \"mention\" for mentions and direct messages only, and \"none\" to disable. Defaults to \"all\"."
},
"desktop_sound": {
"type": "string",
"description": "Set to \"true\" to enable sound on desktop notifications, \"false\" to disable. Defaults to \"true\"."
},
"mention_keys": {
"type": "string",
"description": "A comma-separated list of words to count as mentions. Defaults to username and @username."
},
"channel": {
"type": "string",
"description": "Set to \"true\" to enable channel-wide notifications (@channel, @all, etc.), \"false\" to disable. Defaults to \"true\"."
},
"first_name": {
"type": "string",
"description": "Set to \"true\" to enable mentions for first name. Defaults to \"true\" if a first name is set, \"false\" otherwise."
}
}
},
"props": {
"type": "object"
},
"last_password_update": {
"type": "integer"
},
"last_picture_update": {
"type": "integer"
},
"failed_attempts": {
"type": "integer"
},
"mfa_active": {
"type": "boolean"
},
"timezone": {
"type": "object",
"properties": {
"useAutomaticTimezone": {
"type": "string",
"description": "Set to \"true\" to use the browser/system timezone, \"false\" to set manually. Defaults to \"true\"."
},
"manualTimezone": {
"type": "string",
"description": "Value when setting manually the timezone, i.e. \"Europe/Berlin\"."
},
"automaticTimezone": {
"type": "string",
"description": "This value is set automatically when the \"useAutomaticTimezone\" is set to \"true\"."
}
}
},
"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"
}
}
}
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"Password1\")\n\nteamID := \"4xp9fdt77pncbef59f4k1qe83o\"\nchannelID := \"Ej3SKOHlWIKAblkUTK5Xvkj2cm\"\nusername := \"testUsername\"\n\nusers, resp := Client.AutocompleteUsersInChannel(teamID, channelID, username, 100, \"\")\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",
"responses": {
"200": {
"description": "User stats retrieval successful",
"schema": {
"type": "object",
"properties": {
"total_users_count": {
"type": "integer"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"Password1\")\n\nstats, resp := Client.GetTotalUsersStats(\"\")\n"
}
]
}
},
"/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",
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "User GUID",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "User retrieval successful",
"schema": {
"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": {
"description": "Field only visible to self and admins",
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Set to \"true\" to enable email notifications, \"false\" to disable. Defaults to \"true\"."
},
"push": {
"type": "string",
"description": "Set to \"all\" to receive push notifications for all activity, \"mention\" for mentions and direct messages only, and \"none\" to disable. Defaults to \"mention\"."
},
"desktop": {
"type": "string",
"description": "Set to \"all\" to receive desktop notifications for all activity, \"mention\" for mentions and direct messages only, and \"none\" to disable. Defaults to \"all\"."
},
"desktop_sound": {
"type": "string",
"description": "Set to \"true\" to enable sound on desktop notifications, \"false\" to disable. Defaults to \"true\"."
},
"mention_keys": {
"type": "string",
"description": "A comma-separated list of words to count as mentions. Defaults to username and @username."
},
"channel": {
"type": "string",
"description": "Set to \"true\" to enable channel-wide notifications (@channel, @all, etc.), \"false\" to disable. Defaults to \"true\"."
},
"first_name": {
"type": "string",
"description": "Set to \"true\" to enable mentions for first name. Defaults to \"true\" if a first name is set, \"false\" otherwise."
}
}
},
"props": {
"type": "object"
},
"last_password_update": {
"type": "integer"
},
"last_picture_update": {
"type": "integer"
},
"failed_attempts": {
"type": "integer"
},
"mfa_active": {
"type": "boolean"
},
"timezone": {
"type": "object",
"properties": {
"useAutomaticTimezone": {
"type": "string",
"description": "Set to \"true\" to use the browser/system timezone, \"false\" to set manually. Defaults to \"true\"."
},
"manualTimezone": {
"type": "string",
"description": "Value when setting manually the timezone, i.e. \"Europe/Berlin\"."
},
"automaticTimezone": {
"type": "string",
"description": "This value is set automatically when the \"useAutomaticTimezone\" is set to \"true\"."
}
}
},
"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"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"Password1\")\n\nuserID := \"4xp9fdt77pncbef59f4k1qe83o\"\n\nuser, resp := Client.GetUser(userID, \"\")\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",
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "User GUID",
"required": true,
"type": "string"
},
{
"in": "body",
"name": "body",
"description": "User object that is to be updated",
"required": true,
"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": {
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Set to \"true\" to enable email notifications, \"false\" to disable. Defaults to \"true\"."
},
"push": {
"type": "string",
"description": "Set to \"all\" to receive push notifications for all activity, \"mention\" for mentions and direct messages only, and \"none\" to disable. Defaults to \"mention\"."
},
"desktop": {
"type": "string",
"description": "Set to \"all\" to receive desktop notifications for all activity, \"mention\" for mentions and direct messages only, and \"none\" to disable. Defaults to \"all\"."
},
"desktop_sound": {
"type": "string",
"description": "Set to \"true\" to enable sound on desktop notifications, \"false\" to disable. Defaults to \"true\"."
},
"mention_keys": {
"type": "string",
"description": "A comma-separated list of words to count as mentions. Defaults to username and @username."
},
"channel": {
"type": "string",
"description": "Set to \"true\" to enable channel-wide notifications (@channel, @all, etc.), \"false\" to disable. Defaults to \"true\"."
},
"first_name": {
"type": "string",
"description": "Set to \"true\" to enable mentions for first name. Defaults to \"true\" if a first name is set, \"false\" otherwise."
}
}
}
}
}
}
],
"responses": {
"200": {
"description": "User update successful",
"schema": {
"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": {
"description": "Field only visible to self and admins",
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Set to \"true\" to enable email notifications, \"false\" to disable. Defaults to \"true\"."
},
"push": {
"type": "string",
"description": "Set to \"all\" to receive push notifications for all activity, \"mention\" for mentions and direct messages only, and \"none\" to disable. Defaults to \"mention\"."
},
"desktop": {
"type": "string",
"description": "Set to \"all\" to receive desktop notifications for all activity, \"mention\" for mentions and direct messages only, and \"none\" to disable. Defaults to \"all\"."
},
"desktop_sound": {
"type": "string",
"description": "Set to \"true\" to enable sound on desktop notifications, \"false\" to disable. Defaults to \"true\"."
},
"mention_keys": {
"type": "string",
"description": "A comma-separated list of words to count as mentions. Defaults to username and @username."
},
"channel": {
"type": "string",
"description": "Set to \"true\" to enable channel-wide notifications (@channel, @all, etc.), \"false\" to disable. Defaults to \"true\"."
},
"first_name": {
"type": "string",
"description": "Set to \"true\" to enable mentions for first name. Defaults to \"true\" if a first name is set, \"false\" otherwise."
}
}
},
"props": {
"type": "object"
},
"last_password_update": {
"type": "integer"
},
"last_picture_update": {
"type": "integer"
},
"failed_attempts": {
"type": "integer"
},
"mfa_active": {
"type": "boolean"
},
"timezone": {
"type": "object",
"properties": {
"useAutomaticTimezone": {
"type": "string",
"description": "Set to \"true\" to use the browser/system timezone, \"false\" to set manually. Defaults to \"true\"."
},
"manualTimezone": {
"type": "string",
"description": "Value when setting manually the timezone, i.e. \"Europe/Berlin\"."
},
"automaticTimezone": {
"type": "string",
"description": "This value is set automatically when the \"useAutomaticTimezone\" is set to \"true\"."
}
}
},
"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"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"Password1\")\n\nuserID := \"4xp9fdt77pncbef59f4k1qe83o\"\nemail := \"[email protected]\"\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"
}
]
},
"delete": {
"tags": [
"users"
],
"summary": "Deactivate a user account.",
"description": "Deactivates the user and revokes all its sessions by archiving its user object.\n##### Permissions\nMust be logged in as the user being deactivated or have the `edit_other_users` permission.\n",
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "User GUID",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "User deactivation successful",
"schema": {
"type": "object",
"properties": {
"status": {
"description": "Will contain \"ok\" if the request was successful and there was nothing else to return",
"type": "string"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"Password1\")\n\nuserID := \"4xp9fdt77pncbef59f4k1qe83o\"\n\nok, resp := Client.DeleteUser(userID)\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",
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "User GUID",
"required": true,
"type": "string"
},
{
"in": "body",
"name": "body",
"description": "User object that is to be updated",
"required": true,
"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": {
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Set to \"true\" to enable email notifications, \"false\" to disable. Defaults to \"true\"."
},
"push": {
"type": "string",
"description": "Set to \"all\" to receive push notifications for all activity, \"mention\" for mentions and direct messages only, and \"none\" to disable. Defaults to \"mention\"."
},
"desktop": {
"type": "string",
"description": "Set to \"all\" to receive desktop notifications for all activity, \"mention\" for mentions and direct messages only, and \"none\" to disable. Defaults to \"all\"."
},
"desktop_sound": {
"type": "string",
"description": "Set to \"true\" to enable sound on desktop notifications, \"false\" to disable. Defaults to \"true\"."
},
"mention_keys": {
"type": "string",
"description": "A comma-separated list of words to count as mentions. Defaults to username and @username."
},
"channel": {
"type": "string",
"description": "Set to \"true\" to enable channel-wide notifications (@channel, @all, etc.), \"false\" to disable. Defaults to \"true\"."
},
"first_name": {
"type": "string",
"description": "Set to \"true\" to enable mentions for first name. Defaults to \"true\" if a first name is set, \"false\" otherwise."
}
}
}
}
}
}
],
"responses": {
"200": {
"description": "User patch successful",
"schema": {
"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": {
"description": "Field only visible to self and admins",
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Set to \"true\" to enable email notifications, \"false\" to disable. Defaults to \"true\"."
},
"push": {
"type": "string",
"description": "Set to \"all\" to receive push notifications for all activity, \"mention\" for mentions and direct messages only, and \"none\" to disable. Defaults to \"mention\"."
},
"desktop": {
"type": "string",
"description": "Set to \"all\" to receive desktop notifications for all activity, \"mention\" for mentions and direct messages only, and \"none\" to disable. Defaults to \"all\"."
},
"desktop_sound": {
"type": "string",
"description": "Set to \"true\" to enable sound on desktop notifications, \"false\" to disable. Defaults to \"true\"."
},
"mention_keys": {
"type": "string",
"description": "A comma-separated list of words to count as mentions. Defaults to username and @username."
},
"channel": {
"type": "string",
"description": "Set to \"true\" to enable channel-wide notifications (@channel, @all, etc.), \"false\" to disable. Defaults to \"true\"."
},
"first_name": {
"type": "string",
"description": "Set to \"true\" to enable mentions for first name. Defaults to \"true\" if a first name is set, \"false\" otherwise."
}
}
},
"props": {
"type": "object"
},
"last_password_update": {
"type": "integer"
},
"last_picture_update": {
"type": "integer"
},
"failed_attempts": {
"type": "integer"
},
"mfa_active": {
"type": "boolean"
},
"timezone": {
"type": "object",
"properties": {
"useAutomaticTimezone": {
"type": "string",
"description": "Set to \"true\" to use the browser/system timezone, \"false\" to set manually. Defaults to \"true\"."
},
"manualTimezone": {
"type": "string",
"description": "Value when setting manually the timezone, i.e. \"Europe/Berlin\"."
},
"automaticTimezone": {
"type": "string",
"description": "This value is set automatically when the \"useAutomaticTimezone\" is set to \"true\"."
}
}
},
"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"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"Password1\")\n\nuserID := \"4xp9fdt77pncbef59f4k1qe83o\"\n\npatch := &model.UserPatch{}\npatch.Email = \"[email protected]\"\npatch.Username = \"testUsername\"\npatch.FirstName = \"testFirstname\"\npatch.LastName = \"testLastname\"\npatch.Nickname = \"testNickname\"\npatch.Locale = \"en\"\npatch.Position = \"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"
}
]
}
},
"/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",
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "User GUID",
"required": true,
"type": "string"
},
{
"in": "body",
"name": "roles",
"description": "Space-delimited system roles to assign to the user",
"required": true,
"schema": {
"type": "object",
"required": [
"roles"
],
"properties": {
"roles": {
"type": "string"
}
}
}
}
],
"responses": {
"200": {
"description": "User roles update successful",
"schema": {
"type": "object",
"properties": {
"status": {
"description": "Will contain \"ok\" if the request was successful and there was nothing else to return",
"type": "string"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"Password1\")\n\nuserID := \"4xp9fdt77pncbef59f4k1qe83o\"\nroles := \"team_user team_admin\"\n\nok, resp = Client.UpdateUserRoles(userID, roles)\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",
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "User GUID",
"required": true,
"type": "string"
},
{
"in": "body",
"name": "body",
"description": "Use `true` to set the user active, `false` for inactive",
"required": true,
"schema": {
"type": "object",
"required": [
"active"
],
"properties": {
"active": {
"type": "boolean"
}
}
}
}
],
"responses": {
"200": {
"description": "User active status update successful",
"schema": {
"type": "object",
"properties": {
"status": {
"description": "Will contain \"ok\" if the request was successful and there was nothing else to return",
"type": "string"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"Password1\")\n\nuserID := \"4xp9fdt77pncbef59f4k1qe83o\"\n\nok, resp := Client.UpdateUserActive(userID, true)\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",
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "User GUID",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "User's profile image"
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"501": {
"description": "Feature is disabled",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"Password1\")\n\nuserID := \"4xp9fdt77pncbef59f4k1qe83o\"\n\ndata, resp := Client.GetProfileImage(userID, \"\")\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",
"consumes": [
"multipart/form-data"
],
"parameters": [
{
"name": "image",
"in": "formData",
"description": "The image to be uploaded",
"required": true,
"type": "file"
},
{
"name": "user_id",
"in": "path",
"description": "User GUID",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "Profile image set successful",
"schema": {
"type": "object",
"properties": {
"status": {
"description": "Will contain \"ok\" if the request was successful and there was nothing else to return",
"type": "string"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"501": {
"description": "Feature is disabled",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import (\n \"io/ioutil\"\n \"log\"\n\n \"github.com/mattermost/mattermost-server/model\"\n)\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"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"
}
]
},
"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",
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "User GUID",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "Profile image reset successful",
"schema": {
"type": "object",
"properties": {
"status": {
"description": "Will contain \"ok\" if the request was successful and there was nothing else to return",
"type": "string"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"501": {
"description": "Feature is disabled",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"Password1\")\n\nuserID := \"4xp9fdt77pncbef59f4k1qe83o\"\n\n// Deleting user's profile image consists on resetting it to default one\nok, resp := Client.SetDefaultProfileImage(userID)\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",
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "User GUID",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "Default profile image"
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"501": {
"description": "Feature is disabled",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"Password1\")\n\nuserID := \"4xp9fdt77pncbef59f4k1qe83o\"\n\nok, resp := Client.SetDefaultProfileImage(userID)\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",
"parameters": [
{
"name": "username",
"in": "path",
"description": "Username",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "User retrieval successful",
"schema": {
"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": {
"description": "Field only visible to self and admins",
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Set to \"true\" to enable email notifications, \"false\" to disable. Defaults to \"true\"."
},
"push": {
"type": "string",
"description": "Set to \"all\" to receive push notifications for all activity, \"mention\" for mentions and direct messages only, and \"none\" to disable. Defaults to \"mention\"."
},
"desktop": {
"type": "string",
"description": "Set to \"all\" to receive desktop notifications for all activity, \"mention\" for mentions and direct messages only, and \"none\" to disable. Defaults to \"all\"."
},
"desktop_sound": {
"type": "string",
"description": "Set to \"true\" to enable sound on desktop notifications, \"false\" to disable. Defaults to \"true\"."
},
"mention_keys": {
"type": "string",
"description": "A comma-separated list of words to count as mentions. Defaults to username and @username."
},
"channel": {
"type": "string",
"description": "Set to \"true\" to enable channel-wide notifications (@channel, @all, etc.), \"false\" to disable. Defaults to \"true\"."
},
"first_name": {
"type": "string",
"description": "Set to \"true\" to enable mentions for first name. Defaults to \"true\" if a first name is set, \"false\" otherwise."
}
}
},
"props": {
"type": "object"
},
"last_password_update": {
"type": "integer"
},
"last_picture_update": {
"type": "integer"
},
"failed_attempts": {
"type": "integer"
},
"mfa_active": {
"type": "boolean"
},
"timezone": {
"type": "object",
"properties": {
"useAutomaticTimezone": {
"type": "string",
"description": "Set to \"true\" to use the browser/system timezone, \"false\" to set manually. Defaults to \"true\"."
},
"manualTimezone": {
"type": "string",
"description": "Value when setting manually the timezone, i.e. \"Europe/Berlin\"."
},
"automaticTimezone": {
"type": "string",
"description": "This value is set automatically when the \"useAutomaticTimezone\" is set to \"true\"."
}
}
},
"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"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"Password1\")\n\nuserID := \"4xp9fdt77pncbef59f4k1qe83o\"\n\nuser, resp := Client.GetUserByUsername(userID, \"\")\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",
"parameters": [
{
"in": "body",
"name": "body",
"required": true,
"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"
}
}
}
}
],
"responses": {
"200": {
"description": "User password update successful",
"schema": {
"type": "object",
"properties": {
"status": {
"description": "Will contain \"ok\" if the request was successful and there was nothing else to return",
"type": "string"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"Password1\")\n\ncode := \"4xp9fdt77pncbef59f4k1qe83o\"\nnewPassword := \"awesomePassword\"\n\nsuccess, resp = Client.ResetPassword(code, newPassword)\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",
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "User GUID",
"required": true,
"type": "string"
},
{
"in": "body",
"name": "body",
"required": true,
"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"
}
}
}
}
],
"responses": {
"200": {
"description": "User MFA update successful",
"schema": {
"type": "object",
"properties": {
"status": {
"description": "Will contain \"ok\" if the request was successful and there was nothing else to return",
"type": "string"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"501": {
"description": "Feature is disabled",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"Password1\")\n\nuserID := \"BbaYBYDV5IDOZFiJGBSzkw1k5u\"\ncode := \"4xp9fdt77pncbef59f4k1qe83o\"\n\nok, resp := Client.UpdateUserMfa(userID, code, true)\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",
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "User GUID",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "MFA secret generation successful",
"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": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"501": {
"description": "Feature is disabled",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"Password1\")\n\nuserID := \"BbaYBYDV5IDOZFiJGBSzkw1k5u\"\n\nmfaSecret, resp = Client.GenerateMfaSecret(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",
"parameters": [
{
"in": "body",
"name": "body",
"required": true,
"schema": {
"type": "object",
"required": [
"login_id"
],
"properties": {
"login_id": {
"description": "The email or username used to login",
"type": "string"
}
}
}
}
],
"responses": {
"200": {
"description": "MFA check successful",
"schema": {
"type": "object",
"properties": {
"mfa_required": {
"description": "Value will `true` if MFA is active, `false` otherwise",
"type": "boolean"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\n\nloginID := \"[email protected]\"\n\nrequired, resp := Client.CheckUserMfa(loginID)\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",
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "User GUID",
"required": true,
"type": "string"
},
{
"in": "body",
"name": "body",
"required": true,
"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"
}
}
}
}
],
"responses": {
"200": {
"description": "User password update successful",
"schema": {
"type": "object",
"properties": {
"status": {
"description": "Will contain \"ok\" if the request was successful and there was nothing else to return",
"type": "string"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"Password1\")\n\nuserID := \"BbaYBYDV5IDOZFiJGBSzkw1k5u\"\ncurrentPassword := \"badPassword\"\nnewPassword := \"awesomePassword\"\n\nok, resp := Client.UpdateUserPassword(userID, currentPassword, newPassword)\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",
"parameters": [
{
"in": "body",
"name": "body",
"required": true,
"schema": {
"type": "object",
"required": [
"email"
],
"properties": {
"email": {
"description": "The email of the user",
"type": "string"
}
}
}
}
],
"responses": {
"200": {
"description": "Email sent if account exists",
"schema": {
"type": "object",
"properties": {
"status": {
"description": "Will contain \"ok\" if the request was successful and there was nothing else to return",
"type": "string"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\n\nemail := \"[email protected]\"\n\npass, resp := Client.SendVerificationEmail(email)\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",
"parameters": [
{
"name": "email",
"in": "path",
"description": "User Email",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "User retrieval successful",
"schema": {
"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": {
"description": "Field only visible to self and admins",
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Set to \"true\" to enable email notifications, \"false\" to disable. Defaults to \"true\"."
},
"push": {
"type": "string",
"description": "Set to \"all\" to receive push notifications for all activity, \"mention\" for mentions and direct messages only, and \"none\" to disable. Defaults to \"mention\"."
},
"desktop": {
"type": "string",
"description": "Set to \"all\" to receive desktop notifications for all activity, \"mention\" for mentions and direct messages only, and \"none\" to disable. Defaults to \"all\"."
},
"desktop_sound": {
"type": "string",
"description": "Set to \"true\" to enable sound on desktop notifications, \"false\" to disable. Defaults to \"true\"."
},
"mention_keys": {
"type": "string",
"description": "A comma-separated list of words to count as mentions. Defaults to username and @username."
},
"channel": {
"type": "string",
"description": "Set to \"true\" to enable channel-wide notifications (@channel, @all, etc.), \"false\" to disable. Defaults to \"true\"."
},
"first_name": {
"type": "string",
"description": "Set to \"true\" to enable mentions for first name. Defaults to \"true\" if a first name is set, \"false\" otherwise."
}
}
},
"props": {
"type": "object"
},
"last_password_update": {
"type": "integer"
},
"last_picture_update": {
"type": "integer"
},
"failed_attempts": {
"type": "integer"
},
"mfa_active": {
"type": "boolean"
},
"timezone": {
"type": "object",
"properties": {
"useAutomaticTimezone": {
"type": "string",
"description": "Set to \"true\" to use the browser/system timezone, \"false\" to set manually. Defaults to \"true\"."
},
"manualTimezone": {
"type": "string",
"description": "Value when setting manually the timezone, i.e. \"Europe/Berlin\"."
},
"automaticTimezone": {
"type": "string",
"description": "This value is set automatically when the \"useAutomaticTimezone\" is set to \"true\"."
}
}
},
"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"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"Password1\")\n\nemail := \"[email protected]\"\n\nuser, resp := Client.GetUserByEmail(email, \"\")\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",
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "User GUID",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "User session retrieval successful",
"schema": {
"type": "array",
"items": {
"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": {
"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"
}
}
}
},
"token": {
"type": "string"
},
"user_id": {
"type": "string"
}
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"Password1\")\n\nuserID := \"zWEyrTZ7GZ22aBSfoX60iWryTY\"\n\nsessions, resp := Client.GetSessions(userID, \"\")\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",
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "User GUID",
"required": true,
"type": "string"
},
{
"in": "body",
"name": "body",
"required": true,
"schema": {
"type": "object",
"required": [
"session_id"
],
"properties": {
"session_id": {
"description": "The session GUID to revoke.",
"type": "string"
}
}
}
}
],
"responses": {
"200": {
"description": "User session revoked successful",
"schema": {
"type": "object",
"properties": {
"status": {
"description": "Will contain \"ok\" if the request was successful and there was nothing else to return",
"type": "string"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"Password1\")\n\nuserID := \"zWEyrTZ7GZ22aBSfoX60iWryTY\"\nsessionID := \"adWv1qPZmHdtxk7Lmqh6RtxWxS\"\n\nok, resp = Client.RevokeSession(userID, sessionID)\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",
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "User GUID",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "User sessions revoked successfully",
"schema": {
"type": "object",
"properties": {
"status": {
"description": "Will contain \"ok\" if the request was successful and there was nothing else to return",
"type": "string"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"Password1\")\n\nuserID := \"zWEyrTZ7GZ22aBSfoX60iWryTY\"\n\nok, resp := Client.RevokeAllSessions(userID)\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",
"parameters": [
{
"in": "body",
"name": "body",
"required": true,
"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"
}
}
}
}
],
"responses": {
"200": {
"description": "Device id attach successful",
"schema": {
"type": "object",
"properties": {
"status": {
"description": "Will contain \"ok\" if the request was successful and there was nothing else to return",
"type": "string"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"Password1\")\n\ndeviceID := \"zWEyrTZ7GZ22aBSfoX60iWryTY\"\n\npass, resp := Client.AttachDeviceId(deviceID)\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",
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "User GUID",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "User audits retrieval successful",
"schema": {
"type": "array",
"items": {
"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"
}
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"Password1\")\n\nuserID := \"zWEyrTZ7GZ22aBSfoX60iWryTY\"\n\naudits, resp := Client.GetUserAudits(userID, 0, 100, \"\")\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",
"parameters": [
{
"in": "body",
"name": "body",
"required": true,
"schema": {
"type": "object",
"required": [
"token"
],
"properties": {
"token": {
"description": "The token given to validate the email",
"type": "string"
}
}
}
}
],
"responses": {
"200": {
"description": "User email verification successful",
"schema": {
"type": "object",
"properties": {
"status": {
"description": "Will contain \"ok\" if the request was successful and there was nothing else to return",
"type": "string"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\n\ntoken := \"zWEyrTZ7GZ22aBSfoX60iWryTY\"\n\nok, resp := Client.VerifyUserEmail(token)\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",
"parameters": [
{
"in": "body",
"name": "body",
"required": true,
"schema": {
"type": "object",
"required": [
"email"
],
"properties": {
"email": {
"description": "Email of a user",
"type": "string"
}
}
}
}
],
"responses": {
"200": {
"description": "Email send successful if email exists",
"schema": {
"type": "object",
"properties": {
"status": {
"description": "Will contain \"ok\" if the request was successful and there was nothing else to return",
"type": "string"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\n\nemail := \"[email protected]\"\n\npass, resp := Client.SendVerificationEmail(email)\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",
"parameters": [
{
"in": "body",
"name": "body",
"required": true,
"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"
}
}
}
}
],
"responses": {
"200": {
"description": "Login method switch or request successful",
"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": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"501": {
"description": "Feature is disabled",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\n\ncurrentService := \"email\"\nnewService := \"gitlab\"\nemail := \"[email protected]\"\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"
}
]
}
},
"/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",
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "User GUID",
"required": true,
"type": "string"
},
{
"in": "body",
"name": "token",
"required": true,
"schema": {
"type": "object",
"required": [
"description"
],
"properties": {
"description": {
"description": "A description of the token usage",
"type": "string"
}
}
}
}
],
"responses": {
"201": {
"description": "User access token creation successful",
"schema": {
"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"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"Password1\")\n\nuserID := \"adWv1qPZmHdtxk7Lmqh6RtxWxS\"\n\nuserAccessToken, resp := Client.CreateUserAccessToken(userID, \"test token\")\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",
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "User GUID",
"required": true,
"type": "string"
},
{
"name": "page",
"in": "query",
"description": "The page to select.",
"default": "0",
"type": "string"
},
{
"name": "per_page",
"in": "query",
"description": "The number of tokens per page.",
"default": "60",
"type": "string"
}
],
"responses": {
"200": {
"description": "User access tokens retrieval successful",
"schema": {
"type": "array",
"items": {
"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"
}
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"Password1\")\n\nuserID := \"adWv1qPZmHdtxk7Lmqh6RtxWxS\"\n\ntokens, resp := Client.GetUserAccessTokensForUser(userID, 0, 100)\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",
"parameters": [
{
"name": "page",
"in": "query",
"description": "The page to select.",
"default": "0",
"type": "string"
},
{
"name": "per_page",
"in": "query",
"description": "The number of tokens per page.",
"default": "60",
"type": "string"
}
],
"responses": {
"200": {
"description": "User access tokens retrieval successful",
"schema": {
"type": "array",
"items": {
"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"
}
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"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",
"parameters": [
{
"in": "body",
"name": "token_id",
"required": true,
"schema": {
"type": "object",
"required": [
"token_id"
],
"properties": {
"token_id": {
"description": "The user access token GUID to revoke",
"type": "string"
}
}
}
}
],
"responses": {
"200": {
"description": "User access token revoke successful",
"schema": {
"type": "object",
"properties": {
"status": {
"description": "Will contain \"ok\" if the request was successful and there was nothing else to return",
"type": "string"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"Password1\")\n\ntokenID := \"adWv1qPZmHdtxk7Lmqh6RtxWxS\"\n\nok, resp := Client.RevokeUserAccessToken(tokenID)\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",
"parameters": [
{
"name": "token_id",
"in": "path",
"description": "User access token GUID",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "User access token retrieval successful",
"schema": {
"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"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"Password1\")\n\ntokenID := \"adWv1qPZmHdtxk7Lmqh6RtxWxS\"\n\ntoken, resp := Client.GetUserAccessToken(tokenID)\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",
"parameters": [
{
"in": "body",
"name": "token_id",
"required": true,
"schema": {
"type": "object",
"required": [
"token_id"
],
"properties": {
"token_id": {
"description": "The personal access token GUID to disable",
"type": "string"
}
}
}
}
],
"responses": {
"200": {
"description": "Personal access token disable successful",
"schema": {
"type": "object",
"properties": {
"status": {
"description": "Will contain \"ok\" if the request was successful and there was nothing else to return",
"type": "string"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"Password1\")\n\ntokenID := \"adWv1qPZmHdtxk7Lmqh6RtxWxS\"\n\nok, resp := Client.DisableUserAccessToken(tokenID)\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",
"parameters": [
{
"in": "body",
"name": "token_id",
"required": true,
"schema": {
"type": "object",
"required": [
"token_id"
],
"properties": {
"token_id": {
"description": "The personal access token GUID to enable",
"type": "string"
}
}
}
}
],
"responses": {
"200": {
"description": "Personal access token enable successful",
"schema": {
"type": "object",
"properties": {
"status": {
"description": "Will contain \"ok\" if the request was successful and there was nothing else to return",
"type": "string"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"Password1\")\n\ntokenID := \"adWv1qPZmHdtxk7Lmqh6RtxWxS\"\n\nok, resp := Client.EnableUserAccessToken(tokenID)\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",
"parameters": [
{
"in": "body",
"name": "body",
"description": "Search criteria",
"required": true,
"schema": {
"type": "object",
"required": [
"term"
],
"properties": {
"term": {
"description": "The search term to match against the token id, user id or username.",
"type": "string"
}
}
}
}
],
"responses": {
"200": {
"description": "Personal access token search successful",
"schema": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"Password1\")\n\ntokenID := \"adWv1qPZmHdtxk7Lmqh6RtxWxS\"\n\nuserAccessTokens, resp = Client.SearchUserAccessTokens(&model.UserAccessTokenSearch{Term: tokenID})\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",
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "User GUID",
"required": true,
"type": "string"
},
{
"in": "body",
"name": "body",
"required": true,
"schema": {
"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"
},
"password": {
"description": "The password used for email authentication",
"type": "string"
}
}
}
}
],
"responses": {
"200": {
"description": "User auth update successful",
"schema": {
"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"
},
"password": {
"description": "The password used for email authentication",
"type": "string"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"501": {
"description": "Feature is disabled",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"Password1\")\n\nuserID := \"adWv1qPZmHdtxk7Lmqh6RtxWxS\"\nuser, resp := Client.GetUser(userID, \"\")\nuserAuth := &model.UserAuth{}\nuserAuth.AuthData = user.AuthData\nuserAuth.AuthService = user.AuthService\nuserAuth.Password = user.Password\n\nuser, resp := Client.UpdateUserAuth(userID, userAuth)\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",
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "User GUID",
"required": true,
"type": "string"
},
{
"in": "body",
"name": "body",
"description": "terms of service details",
"required": true,
"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"
}
}
}
}
],
"responses": {
"200": {
"description": "Terms of service action recorded successfully",
"schema": {
"type": "object",
"properties": {
"status": {
"description": "Will contain \"ok\" if the request was successful and there was nothing else to return",
"type": "string"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"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",
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "User GUID",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "User's accepted terms of service action",
"schema": {
"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"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "User hasn't performed an action or the latest action was a rejection.",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"Password1\")\n\nuserID := \"adWv1qPZmHdtxk7Lmqh6RtxWxS\"\n\nuserTermsOfService, resp := Client.GetUserTermsOfService(userID, \"\")\n"
}
]
}
},
"/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",
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "User ID",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "User status retrieval successful",
"schema": {
"type": "object",
"properties": {
"user_id": {
"type": "string"
},
"status": {
"type": "string"
},
"manual": {
"type": "boolean"
},
"last_activity_at": {
"type": "integer",
"format": "int64"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
},
"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",
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "User ID",
"required": true,
"type": "string"
},
{
"name": "body",
"in": "body",
"description": "Status object that is to be updated",
"required": true,
"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`"
}
}
}
}
],
"responses": {
"200": {
"description": "User status update successful",
"schema": {
"type": "object",
"properties": {
"user_id": {
"type": "string"
},
"status": {
"type": "string"
},
"manual": {
"type": "boolean"
},
"last_activity_at": {
"type": "integer",
"format": "int64"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
},
"/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",
"parameters": [
{
"name": "post",
"in": "body",
"description": "List of user ids to fetch",
"required": true,
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
}
],
"responses": {
"200": {
"description": "User statuses retrieval successful",
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"user_id": {
"type": "string"
},
"status": {
"type": "string"
},
"manual": {
"type": "boolean"
},
"last_activity_at": {
"type": "integer",
"format": "int64"
}
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
},
"/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",
"parameters": [
{
"in": "body",
"name": "body",
"description": "Team that is to be created",
"required": true,
"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"
}
}
}
}
],
"responses": {
"201": {
"description": "Team creation successful",
"schema": {
"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"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
},
"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",
"parameters": [
{
"name": "page",
"in": "query",
"description": "The page to select.",
"default": "0",
"type": "string"
},
{
"name": "per_page",
"in": "query",
"description": "The number of teams per page.",
"default": "60",
"type": "string"
}
],
"responses": {
"200": {
"description": "Team list retrieval successful",
"schema": {
"type": "array",
"items": {
"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"
}
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
},
"/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",
"parameters": [
{
"name": "team_id",
"in": "path",
"description": "Team GUID",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "Team retrieval successful",
"schema": {
"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"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
},
"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",
"parameters": [
{
"name": "team_id",
"in": "path",
"description": "Team GUID",
"required": true,
"type": "string"
},
{
"in": "body",
"name": "body",
"description": "Team to update",
"required": true,
"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"
}
}
}
}
],
"responses": {
"200": {
"description": "Team update successful",
"schema": {
"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"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
},
"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",
"parameters": [
{
"name": "team_id",
"in": "path",
"description": "Team GUID",
"required": true,
"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,
"default": false,
"type": "boolean"
}
],
"responses": {
"200": {
"description": "Team deletion successful",
"schema": {
"type": "object",
"properties": {
"status": {
"description": "Will contain \"ok\" if the request was successful and there was nothing else to return",
"type": "string"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
},
"/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",
"parameters": [
{
"name": "team_id",
"in": "path",
"description": "Team GUID",
"required": true,
"type": "string"
},
{
"in": "body",
"name": "body",
"description": "Team object that is to be updated",
"required": true,
"schema": {
"type": "object",
"properties": {
"display_name": {
"type": "string"
},
"description": {
"type": "string"
},
"company_name": {
"type": "string"
},
"invite_id": {
"type": "string"
},
"allow_open_invite": {
"type": "boolean"
}
}
}
}
],
"responses": {
"200": {
"description": "team patch successful",
"schema": {
"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"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
},
"/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",
"parameters": [
{
"name": "name",
"in": "path",
"description": "Team Name",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "Team retrieval successful",
"schema": {
"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"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
},
"/teams/search": {
"post": {
"tags": [
"teams"
],
"summary": "Search teams",
"description": "Search teams based on search term provided in the request body.\n##### Permissions\nLogged in user only shows open teams\nLogged in user with \"manage_system\" permission shows all teams\n",
"parameters": [
{
"in": "body",
"name": "body",
"description": "Search criteria",
"required": true,
"schema": {
"type": "object",
"required": [
"term"
],
"properties": {
"term": {
"description": "The search term to match against the name or display name of teams",
"type": "string"
}
}
}
}
],
"responses": {
"200": {
"description": "Teams search successful",
"schema": {
"type": "array",
"items": {
"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"
}
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
},
"/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",
"parameters": [
{
"name": "name",
"in": "path",
"description": "Team Name",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "Team retrieval successful",
"schema": {
"type": "object",
"properties": {
"exists": {
"type": "boolean"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
},
"/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",
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "User GUID",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "Team list retrieval successful",
"schema": {
"type": "array",
"items": {
"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"
}
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
},
"/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",
"parameters": [
{
"name": "team_id",
"in": "path",
"description": "Team GUID",
"required": true,
"type": "string"
},
{
"name": "page",
"in": "query",
"description": "The page to select.",
"default": "0",
"type": "string"
},
{
"name": "per_page",
"in": "query",
"description": "The number of users per page.",
"default": "60",
"type": "string"
}
],
"responses": {
"200": {
"description": "Team members retrieval successful",
"schema": {
"type": "array",
"items": {
"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"
}
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
},
"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",
"parameters": [
{
"name": "team_id",
"in": "path",
"description": "Team GUID",
"required": true,
"type": "string"
},
{
"in": "body",
"name": "body",
"required": true,
"schema": {
"type": "object",
"properties": {
"team_id": {
"type": "string"
},
"user_id": {
"type": "string"
}
}
}
}
],
"responses": {
"201": {
"description": "Team member creation successful",
"schema": {
"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"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
},
"/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",
"parameters": [
{
"name": "token",
"in": "query",
"description": "Token id from the invitation",
"required": true,
"type": "string"
}
],
"responses": {
"201": {
"description": "Team member creation successful",
"schema": {
"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"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
},
"/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",
"parameters": [
{
"name": "team_id",
"in": "path",
"description": "Team GUID",
"required": true,
"type": "string"
},
{
"in": "body",
"name": "body",
"required": true,
"schema": {
"type": "array",
"items": {
"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"
}
}
}
}
}
],
"responses": {
"201": {
"description": "Team members created successfully.",
"schema": {
"type": "array",
"items": {
"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"
}
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
},
"/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",
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "User GUID",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "Team members retrieval successful",
"schema": {
"type": "array",
"items": {
"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"
}
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
},
"/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",
"parameters": [
{
"name": "team_id",
"in": "path",
"description": "Team GUID",
"required": true,
"type": "string"
},
{
"name": "user_id",
"in": "path",
"description": "User GUID",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "Team member retrieval successful",
"schema": {
"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"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
},
"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",
"parameters": [
{
"name": "team_id",
"in": "path",
"description": "Team GUID",
"required": true,
"type": "string"
},
{
"name": "user_id",
"in": "path",
"description": "User GUID",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "Team member deletion successful",
"schema": {
"type": "object",
"properties": {
"status": {
"description": "Will contain \"ok\" if the request was successful and there was nothing else to return",
"type": "string"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
},
"/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",
"parameters": [
{
"name": "team_id",
"in": "path",
"description": "Team GUID",
"required": true,
"type": "string"
},
{
"in": "body",
"name": "body",
"description": "List of user ids",
"required": true,
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
}
],
"responses": {
"200": {
"description": "Team members retrieval successful",
"schema": {
"type": "array",
"items": {
"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"
}
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
},
"/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",
"parameters": [
{
"name": "team_id",
"in": "path",
"description": "Team GUID",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "Team stats retrieval successful",
"schema": {
"type": "object",
"properties": {
"team_id": {
"type": "string"
},
"total_member_count": {
"type": "integer"
},
"active_member_count": {
"type": "integer"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
},
"/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",
"parameters": [
{
"name": "team_id",
"in": "path",
"description": "Team GUID",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "Team icon retrieval successful"
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"501": {
"description": "Feature is disabled",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
},
"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",
"consumes": [
"multipart/form-data"
],
"parameters": [
{
"name": "team_id",
"in": "path",
"description": "Team GUID",
"required": true,
"type": "string"
},
{
"name": "image",
"in": "formData",
"description": "The image to be uploaded",
"required": true,
"type": "file"
}
],
"responses": {
"200": {
"description": "Team icon successfully set",
"schema": {
"type": "object",
"properties": {
"status": {
"description": "Will contain \"ok\" if the request was successful and there was nothing else to return",
"type": "string"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"500": {
"description": "Something went wrong with the server",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"501": {
"description": "Feature is disabled",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
},
"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",
"parameters": [
{
"name": "team_id",
"in": "path",
"description": "Team GUID",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "Team icon successfully remove",
"schema": {
"type": "object",
"properties": {
"status": {
"description": "Will contain \"ok\" if the request was successful and there was nothing else to return",
"type": "string"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"500": {
"description": "Something went wrong with the server",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"501": {
"description": "Feature is disabled",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
},
"/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",
"parameters": [
{
"name": "team_id",
"in": "path",
"description": "Team GUID",
"required": true,
"type": "string"
},
{
"name": "user_id",
"in": "path",
"description": "User GUID",
"required": true,
"type": "string"
},
{
"in": "body",
"name": "body",
"description": "Space-delimited team roles to assign to the user",
"required": true,
"schema": {
"type": "object",
"required": [
"roles"
],
"properties": {
"roles": {
"type": "string"
}
}
}
}
],
"responses": {
"200": {
"description": "Team member roles update successful",
"schema": {
"type": "object",
"properties": {
"status": {
"description": "Will contain \"ok\" if the request was successful and there was nothing else to return",
"type": "string"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
},
"/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",
"parameters": [
{
"name": "team_id",
"in": "path",
"description": "Team GUID",
"required": true,
"type": "string"
},
{
"name": "user_id",
"in": "path",
"description": "User GUID",
"required": true,
"type": "string"
},
{
"in": "body",
"name": "body",
"description": "Scheme properties.",
"required": true,
"schema": {
"type": "object",
"required": [
"scheme_admin",
"scheme_user"
],
"properties": {
"scheme_admin": {
"type": "boolean"
},
"scheme_user": {
"type": "boolean"
}
}
}
}
],
"responses": {
"200": {
"description": "Team member's scheme-derived roles updated successfully.",
"schema": {
"type": "object",
"properties": {
"status": {
"description": "Will contain \"ok\" if the request was successful and there was nothing else to return",
"type": "string"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
},
"/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",
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "User GUID",
"required": true,
"type": "string"
},
{
"name": "exclude_team",
"in": "query",
"description": "Optional team id to be excluded from the results",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "Team unreads retrieval successful",
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"team_id": {
"type": "string"
},
"msg_count": {
"type": "integer"
},
"mention_count": {
"type": "integer"
}
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
},
"/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",
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "User GUID",
"required": true,
"type": "string"
},
{
"name": "team_id",
"in": "path",
"description": "Team GUID",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "Team unread count retrieval successful",
"schema": {
"type": "object",
"properties": {
"team_id": {
"type": "string"
},
"msg_count": {
"type": "integer"
},
"mention_count": {
"type": "integer"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
},
"/teams/{team_id}/invite/email": {
"post": {
"tags": [
"teams"
],
"summary": "Invite users to the team by email",
"description": "Invite users to the existing team usign the user's email.\n##### Permissions\nMust have `invite_to_team` permission for the team.\n",
"parameters": [
{
"name": "team_id",
"in": "path",
"description": "Team GUID",
"required": true,
"type": "string"
},
{
"in": "body",
"name": "body",
"description": "List of user's email",
"required": true,
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
}
],
"responses": {
"200": {
"description": "Users invite successful",
"schema": {
"type": "object",
"properties": {
"status": {
"description": "Will contain \"ok\" if the request was successful and there was nothing else to return",
"type": "string"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
},
"/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 `manage_system` permission.\n",
"responses": {
"200": {
"description": "Email invites successfully revoked",
"schema": {
"type": "object",
"properties": {
"status": {
"description": "Will contain \"ok\" if the request was successful and there was nothing else to return",
"type": "string"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
},
"/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",
"consumes": [
"multipart/form-data"
],
"parameters": [
{
"name": "file",
"in": "formData",
"description": "A file to be uploaded in zip format.",
"required": true,
"type": "file"
},
{
"name": "filesize",
"in": "formData",
"description": "The size of the zip file to be imported.",
"required": true,
"type": "integer"
},
{
"name": "importFrom",
"in": "formData",
"description": "String that defines from which application the team was exported to be imported into Mattermost.",
"required": true,
"allowEmptyValue": false,
"type": "string"
},
{
"name": "team_id",
"in": "path",
"description": "Team GUID",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "JSON object containing a base64 encoded text file of the import logs in its `results` property.",
"schema": {
"type": "object",
"properties": {
"results": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
},
"/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",
"parameters": [
{
"name": "invite_id",
"in": "path",
"description": "Invite id for a team",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "Team invite info retrieval successful",
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"display_name": {
"type": "string"
},
"description": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
},
"/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",
"parameters": [
{
"name": "team_id",
"in": "path",
"description": "Team GUID",
"required": true,
"type": "string"
},
{
"in": "body",
"name": "body",
"description": "Scheme GUID",
"required": true,
"schema": {
"type": "object",
"required": [
"scheme_id"
],
"properties": {
"scheme_id": {
"type": "string",
"description": "The ID of the scheme."
}
}
}
}
],
"responses": {
"200": {
"description": "Update team scheme successful",
"schema": {
"type": "object",
"properties": {
"status": {
"description": "Will contain \"ok\" if the request was successful and there was nothing else to return",
"type": "string"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"501": {
"description": "Feature is disabled",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"Password1\")\n\nteamID := \"4xp9fdt77pncbef59f4k1qe83o\"\nschemeID := \"qjda3stwafbgpqjaxej3k76sga\"\n\nok, resp := UpdateTeamScheme(teamID, schemeID)\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"
}
]
}
},
"/channels": {
"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",
"parameters": [
{
"in": "body",
"name": "body",
"description": "Channel object to be created",
"required": true,
"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"
}
}
}
}
],
"responses": {
"201": {
"description": "Channel creation successful",
"schema": {
"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"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"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",
"parameters": [
{
"in": "body",
"name": "body",
"description": "The two user ids to be in the direct message",
"required": true,
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
}
],
"responses": {
"201": {
"description": "Direct channel creation successful",
"schema": {
"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"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"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",
"parameters": [
{
"in": "body",
"name": "body",
"description": "User ids to be in the group message channel",
"required": true,
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
}
],
"responses": {
"201": {
"description": "Group channel creation successful",
"schema": {
"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"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"Password1\")\n\nuserIds := []string{<ID OF User1>, <ID OF User2>, <ID OF User3> ...}\n\n// CreateGroupChannel\nrgc, resp := Client.CreateGroupChannel(userIds)\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",
"parameters": [
{
"name": "team_id",
"in": "path",
"description": "Team GUID",
"required": true,
"type": "string"
},
{
"in": "body",
"name": "body",
"description": "List of channel ids",
"required": true,
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
}
],
"responses": {
"200": {
"description": "Channel list retrieval successful",
"schema": {
"type": "array",
"items": {
"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"
}
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"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",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "Channel GUID",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "Timezone retrieval successful",
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"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",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "Channel GUID",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "Channel retrieval successful",
"schema": {
"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"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"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",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "Channel GUID",
"required": true,
"type": "string"
},
{
"in": "body",
"name": "body",
"description": "Channel object to be updated",
"required": true,
"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"
},
"type": {
"type": "string",
"description": "'O' for a public channel, 'P' for a private channel"
}
}
}
}
],
"responses": {
"200": {
"description": "Channel update successful",
"schema": {
"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"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"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##### 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",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "Channel GUID",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "Channel deletion successful",
"schema": {
"type": "object",
"properties": {
"status": {
"description": "Will contain \"ok\" if the request was successful and there was nothing else to return",
"type": "string"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"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",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "Channel GUID",
"required": true,
"type": "string"
},
{
"in": "body",
"name": "body",
"description": "Channel object to be updated",
"required": true,
"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"
}
}
}
}
],
"responses": {
"200": {
"description": "Channel patch successful",
"schema": {
"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"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"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}/convert": {
"post": {
"tags": [
"channels"
],
"summary": "Convert a channel from public to private",
"description": "Convert into private channel from the provided channel id string.\n\n__Minimum server version__: 4.10\n\n##### Permissions\n`manage_team` permission for the team of the channel.\n",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "Channel GUID",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "Channel conversion successful",
"schema": {
"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"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"Password1\")\n\n// ConvertChannelToPrivate\nconvertedChannel, resp := Client.ConvertChannelToPrivate(<CHANNELID>)\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",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "Channel GUID",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "Channel restore successful",
"schema": {
"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"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
},
"/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",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "Channel GUID",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "Channel statistics retrieval successful",
"schema": {
"type": "object",
"properties": {
"channel_id": {
"type": "string"
},
"member_count": {
"type": "integer"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"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.",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "Channel GUID",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "The list of channel pinned posts",
"schema": {
"type": "object",
"properties": {
"order": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"post_id1",
"post_id12"
]
},
"posts": {
"type": "object",
"additionalProperties": {
"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"
},
"parent_id": {
"type": "string"
},
"original_id": {
"type": "string"
},
"message": {
"type": "string"
},
"type": {
"type": "string"
},
"props": {
"type": "object"
},
"hashtag": {
"type": "string"
},
"filenames": {
"description": "This field will only appear on some posts created before Mattermost 3.5 and has since been deprecated.",
"type": "array",
"items": {
"type": "string"
}
},
"file_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"pending_post_id": {
"type": "string"
},
"metadata": {
"description": "Additional information used to display the post. This field is only used to send information from the server\nto the client, and the server will ignore it if it receives it from a client.\n\nThis field will only be returned by servers running Mattermost 5.6 or higher with the experimental\nEnablePostMetadata setting enabled.\n",
"type": "object",
"properties": {
"embeds": {
"type": "array",
"description": "Information about content embedded in the post including OpenGraph previews, image link previews, and\nmessage 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"
]
},
"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\nnull if the post does not contain custom emojis.\n",
"items": {
"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"
}
}
}
},
"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\nany file attachments.\n",
"items": {
"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"
}
}
}
},
"images": {
"type": "object",
"description": "An object mapping the URL of an external image to an object containing the dimensions of that image. This\nfield 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": {
"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"
}
}
}
}
}
}
}
}
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"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",
"parameters": [
{
"name": "team_id",
"in": "path",
"description": "Team GUID",
"required": true,
"type": "string"
},
{
"name": "page",
"in": "query",
"description": "The page to select.",
"default": "0",
"type": "string"
},
{
"name": "per_page",
"in": "query",
"description": "The number of public channels per page.",
"default": "60",
"type": "string"
}
],
"responses": {
"200": {
"description": "Channels retrieval successful",
"schema": {
"type": "array",
"items": {
"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"
}
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"Password1\")\n// GetPublicChannelsForTeam\nchannels, resp := Client.GetPublicChannelsForTeam(<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\n##### Permissions\nMust be authenticated and have the `manage_team` permission.\n",
"parameters": [
{
"name": "team_id",
"in": "path",
"description": "Team GUID",
"required": true,
"type": "string"
},
{
"name": "page",
"in": "query",
"description": "The page to select.",
"default": "0",
"type": "string"
},
{
"name": "per_page",
"in": "query",
"description": "The number of public channels per page.",
"default": "60",
"type": "string"
}
],
"responses": {
"200": {
"description": "Channels retrieval successful",
"schema": {
"type": "array",
"items": {
"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"
}
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
},
"/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",
"parameters": [
{
"name": "team_id",
"in": "path",
"description": "Team GUID",
"required": true,
"type": "string"
},
{
"name": "name",
"in": "query",
"description": "Name or display name",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "Channels autocomplete successful",
"schema": {
"type": "array",
"items": {
"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"
}
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
},
"/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",
"parameters": [
{
"name": "team_id",
"in": "path",
"description": "Team GUID",
"required": true,
"type": "string"
},
{
"name": "name",
"in": "query",
"description": "Name or display name",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "Channels autocomplete successful",
"schema": {
"type": "array",
"items": {
"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"
}
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
},
"/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",
"parameters": [
{
"name": "team_id",
"in": "path",
"description": "Team GUID",
"required": true,
"type": "string"
},
{
"in": "body",
"name": "body",
"description": "Search criteria",
"required": true,
"schema": {
"type": "object",
"required": [
"term"
],
"properties": {
"term": {
"description": "The search term to match against the name or display name of channels",
"type": "string"
}
}
}
}
],
"responses": {
"201": {
"description": "Channels search successful",
"schema": {
"type": "array",
"items": {
"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"
}
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"Password1\")\n\nsearch := &model.ChannelSearch{Term: <CHANNEL DISPLAYNAME>}\n\n// SearchChannels\nchannels, resp := Client.SearchChannels(<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",
"parameters": [
{
"name": "team_id",
"in": "path",
"description": "Team GUID",
"required": true,
"type": "string"
},
{
"name": "channel_name",
"in": "path",
"description": "Channel Name",
"required": true,
"type": "string"
},
{
"name": "include_deleted",
"in": "query",
"description": "Defines if deleted channels should be returned or not",
"type": "string",
"enum": [
true,
false
],
"default": "false"
}
],
"responses": {
"200": {
"description": "Channel retrieval successful",
"schema": {
"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"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"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",
"parameters": [
{
"name": "team_name",
"in": "path",
"description": "Team Name",
"required": true,
"type": "string"
},
{
"name": "channel_name",
"in": "path",
"description": "Channel Name",
"required": true,
"type": "string"
},
{
"name": "include_deleted",
"in": "query",
"description": "Defines if deleted channels should be returned or not",
"type": "string",
"enum": [
true,
false
],
"default": "false"
}
],
"responses": {
"200": {
"description": "Channel retrieval successful",
"schema": {
"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"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"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",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "Channel GUID",
"required": true,
"type": "string"
},
{
"name": "page",
"in": "query",
"description": "The page to select.",
"default": "0",
"type": "string"
},
{
"name": "per_page",
"in": "query",
"description": "The number of members per page.",
"default": "60",
"type": "string"
}
],
"responses": {
"200": {
"description": "Channel members retrieval successful",
"schema": {
"type": "array",
"items": {
"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": {
"description": "Field only visible to self and admins",
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Set to \"true\" to enable email notifications, \"false\" to disable, or \"default\" to use the global user notification setting."
},
"push": {
"type": "string",
"description": "Set to \"all\" to receive push notifications for all activity, \"mention\" for mentions and direct messages only, \"none\" to disable, or \"default\" to use the global user notification setting."
},
"desktop": {
"type": "string",
"description": "Set to \"all\" to receive desktop notifications for all activity, \"mention\" for mentions and direct messages only, \"none\" to disable, or \"default\" to use the global user notification setting."
},
"mark_unread": {
"type": "string",
"description": "Set to \"all\" to mark the channel unread for any new message, \"mention\" to mark unread for new mentions only. Defaults to \"all\"."
}
}
},
"last_update_at": {
"description": "The time in milliseconds the channel member was last updated",
"type": "integer",
"format": "int64"
}
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"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.",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "The channel ID",
"required": true,
"type": "string"
},
{
"in": "body",
"name": "body",
"required": true,
"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"
}
}
}
}
],
"responses": {
"201": {
"description": "Channel member creation successful",
"schema": {
"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": {
"description": "Field only visible to self and admins",
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Set to \"true\" to enable email notifications, \"false\" to disable, or \"default\" to use the global user notification setting."
},
"push": {
"type": "string",
"description": "Set to \"all\" to receive push notifications for all activity, \"mention\" for mentions and direct messages only, \"none\" to disable, or \"default\" to use the global user notification setting."
},
"desktop": {
"type": "string",
"description": "Set to \"all\" to receive desktop notifications for all activity, \"mention\" for mentions and direct messages only, \"none\" to disable, or \"default\" to use the global user notification setting."
},
"mark_unread": {
"type": "string",
"description": "Set to \"all\" to mark the channel unread for any new message, \"mention\" to mark unread for new mentions only. Defaults to \"all\"."
}
}
},
"last_update_at": {
"description": "The time in milliseconds the channel member was last updated",
"type": "integer",
"format": "int64"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"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",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "Channel GUID",
"required": true,
"type": "string"
},
{
"in": "body",
"name": "user_ids",
"description": "List of user ids",
"required": true,
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
}
],
"responses": {
"200": {
"description": "Channel member list retrieval successful",
"schema": {
"type": "array",
"items": {
"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": {
"description": "Field only visible to self and admins",
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Set to \"true\" to enable email notifications, \"false\" to disable, or \"default\" to use the global user notification setting."
},
"push": {
"type": "string",
"description": "Set to \"all\" to receive push notifications for all activity, \"mention\" for mentions and direct messages only, \"none\" to disable, or \"default\" to use the global user notification setting."
},
"desktop": {
"type": "string",
"description": "Set to \"all\" to receive desktop notifications for all activity, \"mention\" for mentions and direct messages only, \"none\" to disable, or \"default\" to use the global user notification setting."
},
"mark_unread": {
"type": "string",
"description": "Set to \"all\" to mark the channel unread for any new message, \"mention\" to mark unread for new mentions only. Defaults to \"all\"."
}
}
},
"last_update_at": {
"description": "The time in milliseconds the channel member was last updated",
"type": "integer",
"format": "int64"
}
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"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",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "Channel GUID",
"required": true,
"type": "string"
},
{
"name": "user_id",
"in": "path",
"description": "User GUID",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "Channel member retrieval successful",
"schema": {
"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": {
"description": "Field only visible to self and admins",
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Set to \"true\" to enable email notifications, \"false\" to disable, or \"default\" to use the global user notification setting."
},
"push": {
"type": "string",
"description": "Set to \"all\" to receive push notifications for all activity, \"mention\" for mentions and direct messages only, \"none\" to disable, or \"default\" to use the global user notification setting."
},
"desktop": {
"type": "string",
"description": "Set to \"all\" to receive desktop notifications for all activity, \"mention\" for mentions and direct messages only, \"none\" to disable, or \"default\" to use the global user notification setting."
},
"mark_unread": {
"type": "string",
"description": "Set to \"all\" to mark the channel unread for any new message, \"mention\" to mark unread for new mentions only. Defaults to \"all\"."
}
}
},
"last_update_at": {
"description": "The time in milliseconds the channel member was last updated",
"type": "integer",
"format": "int64"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"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",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "Channel GUID",
"required": true,
"type": "string"
},
{
"name": "user_id",
"in": "path",
"description": "User GUID",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "Channel member deletion successful",
"schema": {
"type": "object",
"properties": {
"status": {
"description": "Will contain \"ok\" if the request was successful and there was nothing else to return",
"type": "string"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"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",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "Channel GUID",
"required": true,
"type": "string"
},
{
"name": "user_id",
"in": "path",
"description": "User GUID",
"required": true,
"type": "string"
},
{
"in": "body",
"name": "roles",
"description": "Space-delimited channel roles to assign to the user",
"required": true,
"schema": {
"type": "object",
"required": [
"roles"
],
"properties": {
"roles": {
"type": "string"
}
}
}
}
],
"responses": {
"200": {
"description": "Channel roles update successful",
"schema": {
"type": "object",
"properties": {
"status": {
"description": "Will contain \"ok\" if the request was successful and there was nothing else to return",
"type": "string"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"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",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "Channel GUID",
"required": true,
"type": "string"
},
{
"name": "user_id",
"in": "path",
"description": "User GUID",
"required": true,
"type": "string"
},
{
"in": "body",
"name": "body",
"description": "Scheme properties.",
"required": true,
"schema": {
"type": "object",
"required": [
"scheme_admin",
"scheme_user"
],
"properties": {
"scheme_admin": {
"type": "boolean"
},
"scheme_user": {
"type": "boolean"
}
}
}
}
],
"responses": {
"200": {
"description": "Channel member's scheme-derived roles updated successfully.",
"schema": {
"type": "object",
"properties": {
"status": {
"description": "Will contain \"ok\" if the request was successful and there was nothing else to return",
"type": "string"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
},
"/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",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "Channel GUID",
"required": true,
"type": "string"
},
{
"name": "user_id",
"in": "path",
"description": "User GUID",
"required": true,
"type": "string"
},
{
"in": "body",
"name": "notify_props",
"required": true,
"schema": {
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Set to \"true\" to enable email notifications, \"false\" to disable, or \"default\" to use the global user notification setting."
},
"push": {
"type": "string",
"description": "Set to \"all\" to receive push notifications for all activity, \"mention\" for mentions and direct messages only, \"none\" to disable, or \"default\" to use the global user notification setting."
},
"desktop": {
"type": "string",
"description": "Set to \"all\" to receive desktop notifications for all activity, \"mention\" for mentions and direct messages only, \"none\" to disable, or \"default\" to use the global user notification setting."
},
"mark_unread": {
"type": "string",
"description": "Set to \"all\" to mark the channel unread for any new message, \"mention\" to mark unread for new mentions only. Defaults to \"all\"."
}
}
}
}
],
"responses": {
"200": {
"description": "Channel notification properties update successful",
"schema": {
"type": "object",
"properties": {
"status": {
"description": "Will contain \"ok\" if the request was successful and there was nothing else to return",
"type": "string"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"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",
"parameters": [
{
"in": "path",
"name": "user_id",
"description": "User ID to perform the view action for",
"required": true,
"type": "string"
},
{
"in": "body",
"name": "body",
"description": "Paremeters affecting how and which channels to view",
"required": true,
"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."
}
}
}
}
],
"responses": {
"200": {
"description": "Channel view successful",
"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": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"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 members for user",
"description": "Get all channel members on a team for a user.\n##### Permissions\nLogged in as the user and `view_team` permission for the team. Having `manage_system` permission voids the previous requirements.\n",
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "User GUID",
"required": true,
"type": "string"
},
{
"name": "team_id",
"in": "path",
"description": "Team GUID",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "Channel members retrieval successful",
"schema": {
"type": "array",
"items": {
"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": {
"description": "Field only visible to self and admins",
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Set to \"true\" to enable email notifications, \"false\" to disable, or \"default\" to use the global user notification setting."
},
"push": {
"type": "string",
"description": "Set to \"all\" to receive push notifications for all activity, \"mention\" for mentions and direct messages only, \"none\" to disable, or \"default\" to use the global user notification setting."
},
"desktop": {
"type": "string",
"description": "Set to \"all\" to receive desktop notifications for all activity, \"mention\" for mentions and direct messages only, \"none\" to disable, or \"default\" to use the global user notification setting."
},
"mark_unread": {
"type": "string",
"description": "Set to \"all\" to mark the channel unread for any new message, \"mention\" to mark unread for new mentions only. Defaults to \"all\"."
}
}
},
"last_update_at": {
"description": "The time in milliseconds the channel member was last updated",
"type": "integer",
"format": "int64"
}
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"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",
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "User GUID",
"required": true,
"type": "string"
},
{
"name": "team_id",
"in": "path",
"description": "Team GUID",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "Channels retrieval successful",
"schema": {
"type": "array",
"items": {
"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"
}
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"Password1\")\n\n// GetChannelsForTeamForUser\nchannels, resp := Client.GetChannelsForTeamForUser(<TEAMID>, <USERID>, \"\")\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",
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "User GUID",
"required": true,
"type": "string"
},
{
"name": "channel_id",
"in": "path",
"description": "Channel GUID",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "Channel unreads retrieval successful",
"schema": {
"type": "object",
"properties": {
"team_id": {
"type": "string"
},
"channel_id": {
"type": "string"
},
"msg_count": {
"type": "integer"
},
"mention_count": {
"type": "integer"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"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",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "Channel GUID",
"required": true,
"type": "string"
},
{
"in": "body",
"name": "body",
"description": "Scheme GUID",
"required": true,
"schema": {
"type": "object",
"required": [
"scheme_id"
],
"properties": {
"scheme_id": {
"type": "string",
"description": "The ID of the scheme."
}
}
}
}
],
"responses": {
"200": {
"description": "Update channel scheme successful",
"schema": {
"type": "object",
"properties": {
"status": {
"description": "Will contain \"ok\" if the request was successful and there was nothing else to return",
"type": "string"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"501": {
"description": "Feature is disabled",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"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"
}
]
}
},
"/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",
"parameters": [
{
"in": "body",
"name": "post",
"description": "Post object to create",
"required": true,
"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"
}
}
}
}
],
"responses": {
"201": {
"description": "Post creation successful",
"schema": {
"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"
},
"parent_id": {
"type": "string"
},
"original_id": {
"type": "string"
},
"message": {
"type": "string"
},
"type": {
"type": "string"
},
"props": {
"type": "object"
},
"hashtag": {
"type": "string"
},
"filenames": {
"description": "This field will only appear on some posts created before Mattermost 3.5 and has since been deprecated.",
"type": "array",
"items": {
"type": "string"
}
},
"file_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"pending_post_id": {
"type": "string"
},
"metadata": {
"description": "Additional information used to display the post. This field is only used to send information from the server\nto the client, and the server will ignore it if it receives it from a client.\n\nThis field will only be returned by servers running Mattermost 5.6 or higher with the experimental\nEnablePostMetadata setting enabled.\n",
"type": "object",
"properties": {
"embeds": {
"type": "array",
"description": "Information about content embedded in the post including OpenGraph previews, image link previews, and\nmessage 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"
]
},
"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\nnull if the post does not contain custom emojis.\n",
"items": {
"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"
}
}
}
},
"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\nany file attachments.\n",
"items": {
"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"
}
}
}
},
"images": {
"type": "object",
"description": "An object mapping the URL of an external image to an object containing the dimensions of that image. This\nfield 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": {
"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"
}
}
}
}
}
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
},
"/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",
"parameters": [
{
"in": "body",
"name": "ephemeral_post",
"description": "Ephemeral Post object to send",
"required": true,
"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"
}
}
}
}
}
}
],
"responses": {
"201": {
"description": "Post creation successful",
"schema": {
"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"
},
"parent_id": {
"type": "string"
},
"original_id": {
"type": "string"
},
"message": {
"type": "string"
},
"type": {
"type": "string"
},
"props": {
"type": "object"
},
"hashtag": {
"type": "string"
},
"filenames": {
"description": "This field will only appear on some posts created before Mattermost 3.5 and has since been deprecated.",
"type": "array",
"items": {
"type": "string"
}
},
"file_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"pending_post_id": {
"type": "string"
},
"metadata": {
"description": "Additional information used to display the post. This field is only used to send information from the server\nto the client, and the server will ignore it if it receives it from a client.\n\nThis field will only be returned by servers running Mattermost 5.6 or higher with the experimental\nEnablePostMetadata setting enabled.\n",
"type": "object",
"properties": {
"embeds": {
"type": "array",
"description": "Information about content embedded in the post including OpenGraph previews, image link previews, and\nmessage 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"
]
},
"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\nnull if the post does not contain custom emojis.\n",
"items": {
"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"
}
}
}
},
"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\nany file attachments.\n",
"items": {
"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"
}
}
}
},
"images": {
"type": "object",
"description": "An object mapping the URL of an external image to an object containing the dimensions of that image. This\nfield 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": {
"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"
}
}
}
}
}
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "client := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nclient.Login(\"[email protected]\", \"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",
"parameters": [
{
"name": "post_id",
"in": "path",
"description": "ID of the post to get",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "Post retrieval successful",
"schema": {
"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"
},
"parent_id": {
"type": "string"
},
"original_id": {
"type": "string"
},
"message": {
"type": "string"
},
"type": {
"type": "string"
},
"props": {
"type": "object"
},
"hashtag": {
"type": "string"
},
"filenames": {
"description": "This field will only appear on some posts created before Mattermost 3.5 and has since been deprecated.",
"type": "array",
"items": {
"type": "string"
}
},
"file_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"pending_post_id": {
"type": "string"
},
"metadata": {
"description": "Additional information used to display the post. This field is only used to send information from the server\nto the client, and the server will ignore it if it receives it from a client.\n\nThis field will only be returned by servers running Mattermost 5.6 or higher with the experimental\nEnablePostMetadata setting enabled.\n",
"type": "object",
"properties": {
"embeds": {
"type": "array",
"description": "Information about content embedded in the post including OpenGraph previews, image link previews, and\nmessage 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"
]
},
"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\nnull if the post does not contain custom emojis.\n",
"items": {
"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"
}
}
}
},
"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\nany file attachments.\n",
"items": {
"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"
}
}
}
},
"images": {
"type": "object",
"description": "An object mapping the URL of an external image to an object containing the dimensions of that image. This\nfield 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": {
"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"
}
}
}
}
}
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
},
"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",
"parameters": [
{
"name": "post_id",
"in": "path",
"description": "ID of the post to delete",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "Post deletion successful",
"schema": {
"type": "object",
"properties": {
"status": {
"description": "Will contain \"ok\" if the request was successful and there was nothing else to return",
"type": "string"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
},
"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",
"parameters": [
{
"name": "post_id",
"in": "path",
"description": "ID of the post to update",
"required": true,
"type": "string"
},
{
"in": "body",
"name": "body",
"description": "Post object that is to be updated",
"required": true,
"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"
},
"file_ids": {
"description": "The list of files attached to this post",
"type": "array"
},
"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"
}
}
}
}
],
"responses": {
"200": {
"description": "Post update successful",
"schema": {
"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"
},
"parent_id": {
"type": "string"
},
"original_id": {
"type": "string"
},
"message": {
"type": "string"
},
"type": {
"type": "string"
},
"props": {
"type": "object"
},
"hashtag": {
"type": "string"
},
"filenames": {
"description": "This field will only appear on some posts created before Mattermost 3.5 and has since been deprecated.",
"type": "array",
"items": {
"type": "string"
}
},
"file_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"pending_post_id": {
"type": "string"
},
"metadata": {
"description": "Additional information used to display the post. This field is only used to send information from the server\nto the client, and the server will ignore it if it receives it from a client.\n\nThis field will only be returned by servers running Mattermost 5.6 or higher with the experimental\nEnablePostMetadata setting enabled.\n",
"type": "object",
"properties": {
"embeds": {
"type": "array",
"description": "Information about content embedded in the post including OpenGraph previews, image link previews, and\nmessage 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"
]
},
"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\nnull if the post does not contain custom emojis.\n",
"items": {
"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"
}
}
}
},
"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\nany file attachments.\n",
"items": {
"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"
}
}
}
},
"images": {
"type": "object",
"description": "An object mapping the URL of an external image to an object containing the dimensions of that image. This\nfield 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": {
"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"
}
}
}
}
}
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
},
"/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",
"parameters": [
{
"name": "post_id",
"in": "path",
"description": "Post GUID",
"required": true,
"type": "string"
},
{
"in": "body",
"name": "body",
"description": "Post object that is to be updated",
"required": true,
"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"
},
"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"
}
}
}
}
],
"responses": {
"200": {
"description": "Post patch successful",
"schema": {
"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"
},
"parent_id": {
"type": "string"
},
"original_id": {
"type": "string"
},
"message": {
"type": "string"
},
"type": {
"type": "string"
},
"props": {
"type": "object"
},
"hashtag": {
"type": "string"
},
"filenames": {
"description": "This field will only appear on some posts created before Mattermost 3.5 and has since been deprecated.",
"type": "array",
"items": {
"type": "string"
}
},
"file_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"pending_post_id": {
"type": "string"
},
"metadata": {
"description": "Additional information used to display the post. This field is only used to send information from the server\nto the client, and the server will ignore it if it receives it from a client.\n\nThis field will only be returned by servers running Mattermost 5.6 or higher with the experimental\nEnablePostMetadata setting enabled.\n",
"type": "object",
"properties": {
"embeds": {
"type": "array",
"description": "Information about content embedded in the post including OpenGraph previews, image link previews, and\nmessage 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"
]
},
"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\nnull if the post does not contain custom emojis.\n",
"items": {
"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"
}
}
}
},
"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\nany file attachments.\n",
"items": {
"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"
}
}
}
},
"images": {
"type": "object",
"description": "An object mapping the URL of an external image to an object containing the dimensions of that image. This\nfield 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": {
"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"
}
}
}
}
}
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
},
"/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",
"parameters": [
{
"name": "post_id",
"in": "path",
"description": "ID of a post in the thread",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "Post list retrieval successful",
"schema": {
"type": "object",
"properties": {
"order": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"post_id1",
"post_id12"
]
},
"posts": {
"type": "object",
"additionalProperties": {
"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"
},
"parent_id": {
"type": "string"
},
"original_id": {
"type": "string"
},
"message": {
"type": "string"
},
"type": {
"type": "string"
},
"props": {
"type": "object"
},
"hashtag": {
"type": "string"
},
"filenames": {
"description": "This field will only appear on some posts created before Mattermost 3.5 and has since been deprecated.",
"type": "array",
"items": {
"type": "string"
}
},
"file_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"pending_post_id": {
"type": "string"
},
"metadata": {
"description": "Additional information used to display the post. This field is only used to send information from the server\nto the client, and the server will ignore it if it receives it from a client.\n\nThis field will only be returned by servers running Mattermost 5.6 or higher with the experimental\nEnablePostMetadata setting enabled.\n",
"type": "object",
"properties": {
"embeds": {
"type": "array",
"description": "Information about content embedded in the post including OpenGraph previews, image link previews, and\nmessage 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"
]
},
"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\nnull if the post does not contain custom emojis.\n",
"items": {
"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"
}
}
}
},
"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\nany file attachments.\n",
"items": {
"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"
}
}
}
},
"images": {
"type": "object",
"description": "An object mapping the URL of an external image to an object containing the dimensions of that image. This\nfield 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": {
"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"
}
}
}
}
}
}
}
}
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
},
"/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.\n##### Permissions\nMust be user or have `manage_system` permission.\n",
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "ID of the user",
"required": true,
"type": "string"
},
{
"name": "team_id",
"in": "query",
"description": "Team ID",
"type": "string"
},
{
"name": "channel_id",
"in": "query",
"description": "Channel ID",
"type": "string"
},
{
"name": "page",
"in": "query",
"description": "The page to select",
"default": "0",
"type": "string"
},
{
"name": "per_page",
"in": "query",
"description": "The number of posts per page",
"default": "60",
"type": "string"
}
],
"responses": {
"200": {
"description": "Post list retrieval successful",
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"order": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"post_id1",
"post_id12"
]
},
"posts": {
"type": "object",
"additionalProperties": {
"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"
},
"parent_id": {
"type": "string"
},
"original_id": {
"type": "string"
},
"message": {
"type": "string"
},
"type": {
"type": "string"
},
"props": {
"type": "object"
},
"hashtag": {
"type": "string"
},
"filenames": {
"description": "This field will only appear on some posts created before Mattermost 3.5 and has since been deprecated.",
"type": "array",
"items": {
"type": "string"
}
},
"file_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"pending_post_id": {
"type": "string"
},
"metadata": {
"description": "Additional information used to display the post. This field is only used to send information from the server\nto the client, and the server will ignore it if it receives it from a client.\n\nThis field will only be returned by servers running Mattermost 5.6 or higher with the experimental\nEnablePostMetadata setting enabled.\n",
"type": "object",
"properties": {
"embeds": {
"type": "array",
"description": "Information about content embedded in the post including OpenGraph previews, image link previews, and\nmessage 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"
]
},
"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\nnull if the post does not contain custom emojis.\n",
"items": {
"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"
}
}
}
},
"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\nany file attachments.\n",
"items": {
"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"
}
}
}
},
"images": {
"type": "object",
"description": "An object mapping the URL of an external image to an object containing the dimensions of that image. This\nfield 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": {
"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"
}
}
}
}
}
}
}
}
}
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
},
"/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",
"parameters": [
{
"name": "post_id",
"in": "path",
"description": "ID of the post",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "File info retrieval successful",
"schema": {
"type": "array",
"items": {
"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"
}
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
},
"/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 parameters `since`, `before` and `after` must not be used together.\n##### Permissions\nMust have `read_channel` permission for the channel.\n",
"parameters": [
{
"name": "channel_id",
"in": "path",
"description": "The channel ID to get the posts for",
"required": true,
"type": "string"
},
{
"name": "page",
"in": "query",
"description": "The page to select",
"default": "0",
"type": "string"
},
{
"name": "per_page",
"in": "query",
"description": "The number of posts per page",
"default": "60",
"type": "string"
},
{
"name": "since",
"in": "query",
"description": "Provide a non-zero value in Unix time milliseconds to select posts created after that time",
"type": "integer"
},
{
"name": "before",
"in": "query",
"description": "A post id to select the posts that came before this one",
"type": "string"
},
{
"name": "after",
"in": "query",
"description": "A post id to select the posts that came after this one",
"type": "string"
}
],
"responses": {
"200": {
"description": "Post list retrieval successful",
"schema": {
"type": "object",
"properties": {
"order": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"post_id1",
"post_id12"
]
},
"posts": {
"type": "object",
"additionalProperties": {
"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"
},
"parent_id": {
"type": "string"
},
"original_id": {
"type": "string"
},
"message": {
"type": "string"
},
"type": {
"type": "string"
},
"props": {
"type": "object"
},
"hashtag": {
"type": "string"
},
"filenames": {
"description": "This field will only appear on some posts created before Mattermost 3.5 and has since been deprecated.",
"type": "array",
"items": {
"type": "string"
}
},
"file_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"pending_post_id": {
"type": "string"
},
"metadata": {
"description": "Additional information used to display the post. This field is only used to send information from the server\nto the client, and the server will ignore it if it receives it from a client.\n\nThis field will only be returned by servers running Mattermost 5.6 or higher with the experimental\nEnablePostMetadata setting enabled.\n",
"type": "object",
"properties": {
"embeds": {
"type": "array",
"description": "Information about content embedded in the post including OpenGraph previews, image link previews, and\nmessage 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"
]
},
"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\nnull if the post does not contain custom emojis.\n",
"items": {
"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"
}
}
}
},
"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\nany file attachments.\n",
"items": {
"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"
}
}
}
},
"images": {
"type": "object",
"description": "An object mapping the URL of an external image to an object containing the dimensions of that image. This\nfield 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": {
"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"
}
}
}
}
}
}
}
}
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
},
"/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",
"parameters": [
{
"name": "team_id",
"in": "path",
"description": "Team GUID",
"required": true,
"type": "string"
},
{
"name": "body",
"in": "body",
"description": "The search terms and logic to use in the search.",
"required": true,
"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)"
}
}
}
}
],
"responses": {
"200": {
"description": "Post list retrieval successful",
"schema": {
"type": "object",
"properties": {
"order": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"post_id1",
"post_id12"
]
},
"posts": {
"type": "object",
"additionalProperties": {
"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"
},
"parent_id": {
"type": "string"
},
"original_id": {
"type": "string"
},
"message": {
"type": "string"
},
"type": {
"type": "string"
},
"props": {
"type": "object"
},
"hashtag": {
"type": "string"
},
"filenames": {
"description": "This field will only appear on some posts created before Mattermost 3.5 and has since been deprecated.",
"type": "array",
"items": {
"type": "string"
}
},
"file_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"pending_post_id": {
"type": "string"
},
"metadata": {
"description": "Additional information used to display the post. This field is only used to send information from the server\nto the client, and the server will ignore it if it receives it from a client.\n\nThis field will only be returned by servers running Mattermost 5.6 or higher with the experimental\nEnablePostMetadata setting enabled.\n",
"type": "object",
"properties": {
"embeds": {
"type": "array",
"description": "Information about content embedded in the post including OpenGraph previews, image link previews, and\nmessage 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"
]
},
"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\nnull if the post does not contain custom emojis.\n",
"items": {
"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"
}
}
}
},
"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\nany file attachments.\n",
"items": {
"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"
}
}
}
},
"images": {
"type": "object",
"description": "An object mapping the URL of an external image to an object containing the dimensions of that image. This\nfield 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": {
"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"
}
}
}
}
}
}
}
}
},
"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"
]
}
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
},
"/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",
"parameters": [
{
"name": "post_id",
"in": "path",
"description": "Post GUID",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "Pinned post successful",
"schema": {
"type": "object",
"properties": {
"status": {
"description": "Will contain \"ok\" if the request was successful and there was nothing else to return",
"type": "string"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
},
"/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",
"parameters": [
{
"name": "post_id",
"in": "path",
"description": "Post GUID",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "Unpinned post successful",
"schema": {
"type": "object",
"properties": {
"status": {
"description": "Will contain \"ok\" if the request was successful and there was nothing else to return",
"type": "string"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
},
"/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",
"parameters": [
{
"name": "post_id",
"in": "path",
"description": "Post GUID",
"required": true,
"type": "string"
},
{
"name": "action_id",
"in": "path",
"description": "Action GUID",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "Post action successful",
"schema": {
"type": "object",
"properties": {
"status": {
"description": "Will contain \"ok\" if the request was successful and there was nothing else to return",
"type": "string"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
},
"/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",
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "User GUID",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "User preferences retrieval successful",
"schema": {
"type": "array",
"items": {
"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"
}
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
},
"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",
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "User GUID",
"required": true,
"type": "string"
},
{
"in": "body",
"name": "body",
"description": "List of preference object",
"required": true,
"schema": {
"type": "array",
"items": {
"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"
}
}
}
}
}
],
"responses": {
"200": {
"description": "User preferences saved successful",
"schema": {
"type": "object",
"properties": {
"status": {
"description": "Will contain \"ok\" if the request was successful and there was nothing else to return",
"type": "string"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
},
"/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",
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "User GUID",
"required": true,
"type": "string"
},
{
"in": "body",
"name": "body",
"description": "List of preference object",
"required": true,
"schema": {
"type": "array",
"items": {
"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"
}
}
}
}
}
],
"responses": {
"200": {
"description": "User preferences saved successful",
"schema": {
"type": "object",
"properties": {
"status": {
"description": "Will contain \"ok\" if the request was successful and there was nothing else to return",
"type": "string"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
},
"/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",
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "User GUID",
"required": true,
"type": "string"
},
{
"name": "category",
"in": "path",
"description": "The category of a group of preferences",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "A list of all of the current user's preferences in the given category",
"schema": {
"type": "array",
"items": {
"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"
}
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
},
"/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",
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "User GUID",
"required": true,
"type": "string"
},
{
"name": "category",
"in": "path",
"description": "The category of a group of preferences",
"required": true,
"type": "string"
},
{
"name": "preference_name",
"in": "path",
"description": "The name of the preference",
"required": true,
"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",
"schema": {
"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"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
},
"/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",
"consumes": [
"multipart/form-data",
"*/*"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "files",
"in": "formData",
"description": "A file to be uploaded",
"required": false,
"type": "file"
},
{
"name": "channel_id",
"in": "formData",
"description": "The ID of the channel that this file will be uploaded to",
"required": false,
"type": "string"
},
{
"name": "client_ids",
"in": "formData",
"description": "A unique identifier for the file that will be returned in the response",
"required": false,
"allowEmptyValue": true,
"type": "string"
},
{
"name": "channel_id",
"in": "query",
"description": "The ID of the channel that this file will be uploaded to",
"required": false,
"type": "string"
},
{
"name": "filename",
"in": "query",
"description": "The name of the file to be uploaded",
"required": false,
"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",
"schema": {
"type": "object",
"properties": {
"file_infos": {
"description": "A list of file metadata that has been stored in the database",
"type": "array",
"items": {
"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"
}
}
}
},
"client_ids": {
"description": "A list of the client_ids that were provided in the request",
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"413": {
"description": "Content too large",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"501": {
"description": "Feature is disabled",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"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",
"parameters": [
{
"name": "file_id",
"in": "path",
"description": "The ID of the file to get",
"required": true,
"type": "string"
}
],
"responses": {
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"501": {
"description": "Feature is disabled",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"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",
"parameters": [
{
"name": "file_id",
"in": "path",
"description": "The ID of the file to get",
"required": true,
"type": "string"
}
],
"responses": {
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"501": {
"description": "Feature is disabled",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"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",
"parameters": [
{
"name": "file_id",
"in": "path",
"description": "The ID of the file to get",
"required": true,
"type": "string"
}
],
"responses": {
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"501": {
"description": "Feature is disabled",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"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",
"parameters": [
{
"name": "file_id",
"in": "path",
"description": "The ID of the file to get a link for",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "A publicly accessible link to the given file",
"schema": {
"type": "object",
"properties": {
"link": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"501": {
"description": "Feature is disabled",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"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",
"parameters": [
{
"name": "file_id",
"in": "path",
"description": "The ID of the file info to get",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "The stored metadata for the given file",
"schema": {
"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"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"501": {
"description": "Feature is disabled",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"Password1\")\n\nfileID := \"4xp9fdt77pncbef59f4k1qe83o\"\n\ninfo, resp := Client.GetFileInfo(fileID)\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",
"parameters": [
{
"name": "page",
"in": "query",
"description": "The page to select.",
"default": "0",
"type": "string"
},
{
"name": "per_page",
"in": "query",
"description": "The number of jobs per page.",
"default": "60",
"type": "string"
}
],
"responses": {
"200": {
"description": "Job list retrieval successful",
"schema": {
"type": "array",
"items": {
"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"
}
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
},
"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",
"parameters": [
{
"in": "body",
"name": "body",
"description": "Job object to be created",
"required": true,
"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"
}
}
}
}
],
"responses": {
"201": {
"description": "Job creation successful",
"schema": {
"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"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
},
"/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",
"parameters": [
{
"name": "job_id",
"in": "path",
"description": "Job GUID",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "Job retrieval successful",
"schema": {
"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"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
},
"/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",
"parameters": [
{
"name": "job_id",
"in": "path",
"description": "Job GUID",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "Job canceled successfully",
"schema": {
"type": "object",
"properties": {
"status": {
"description": "Will contain \"ok\" if the request was successful and there was nothing else to return",
"type": "string"
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"404": {
"description": "Resource not found",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
},
"/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",
"parameters": [
{
"name": "type",
"in": "path",
"description": "Job type",
"required": true,
"type": "string"
},
{
"name": "page",
"in": "query",
"description": "The page to select.",
"default": "0",
"type": "string"
},
{
"name": "per_page",
"in": "query",
"description": "The number of jobs per page.",
"default": "60",
"type": "string"
}
],
"responses": {
"200": {
"description": "Job list retrieval successful",
"schema": {
"type": "array",
"items": {
"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"
}
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"401": {
"description": "No access token provided",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
},
"/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",
"responses": {
"200": {
"description": "Status of the system",
"schema": {
"type": "object",
"properties": {
"status": {
"description": "Will contain \"ok\" if the request was successful and there was nothing else to return",
"type": "string"
}
}
}
},
"500": {
"schema": {
"type": "object",
"items": {
"type": "string"
}
},
"description": "Something went wrong with the server"
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"Password1\")\n\n// GetPing\nstatus, resp := Client.GetPing()\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",
"responses": {
"200": {
"description": "Database recycle successful",
"schema": {
"type": "object",
"properties": {
"status": {
"description": "Will contain \"ok\" if the request was successful and there was nothing else to return",
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"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",
"parameters": [
{
"in": "body",
"name": "body",
"description": "Mattermost configuration",
"required": true,
"schema": {
"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"
}
}
}
}
}
}
],
"responses": {
"200": {
"description": "Email successful sent",
"schema": {
"type": "object",
"properties": {
"status": {
"description": "Will contain \"ok\" if the request was successful and there was nothing else to return",
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"500": {
"description": "Something went wrong with the server",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"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"
}
]
}
},
"/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",
"parameters": [
{
"in": "body",
"name": "body",
"description": "Mattermost configuration",
"required": true,
"schema": {
"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"
}
}
}
}
}
}
],
"responses": {
"200": {
"description": "S3 Test successful",
"schema": {
"type": "object",
"properties": {
"status": {
"description": "Will contain \"ok\" if the request was successful and there was nothing else to return",
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"500": {
"description": "Something went wrong with the server",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"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",
"responses": {
"200": {
"description": "Configuration retrieval successful",
"schema": {
"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"
}
}
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"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",
"parameters": [
{
"in": "body",
"name": "body",
"description": "Mattermost configuration",
"required": true,
"schema": {
"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"
}
}
}
}
}
}
],
"responses": {
"200": {
"description": "Configuration update successful",
"schema": {
"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"
}
}
}
}
}
},
"400": {
"description": "Invalid or missing parameters in URL or request body",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
},
"403": {
"description": "Do not have appropriate permissions",
"schema": {
"type": "object",
"properties": {
"status_code": {
"type": "integer"
},
"id": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
},
"x-code-samples": [
{
"lang": "Go",
"source": "import \"github.com/mattermost/mattermost-server/model\"\n\nClient := model.NewAPIv4Client(\"https://your-mattermost-url.com\")\nClient.Login(\"[email protected]\", \"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",
"responses": {
"200": {
"description": "Configuration reload successful",
"schema": {
"type": "object",
"properties": {
"status": {
"description": "Will contain \"ok\" if the request was successful and there was nothing else to return",
"type": "string"
}
}
}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment