diff --git a/api/redoc-static.html b/api/redoc-static.html deleted file mode 100644 index 0c6b2011e8..0000000000 --- a/api/redoc-static.html +++ /dev/null @@ -1,4362 +0,0 @@ - - - - - - Mattermost API Reference - - - - - - - - - - -
logo
Documentation Powered by ReDoc

Mattermost API Reference (4.0.0)

Download OpenAPI specification:Download

E-mail: feedback@mattermost.com Terms of Service

There is also a work-in-progress Postman API reference.

-
Mattermost is an open source platform for secure collaboration across the entire software development lifecycle. This is the reference documentation for the Mattermost REST API.

Authentication

bearerAuth

Security Scheme Type HTTP
HTTP Authorization Scheme bearer
Bearer format "Token"

introduction

The Mattermost Web Services API is used by Mattermost clients and third party applications to interact with the server. JavaScript and Golang drivers for connecting to the APIs are also available.

-

Support

-

Mattermost core committers work with the community to keep the API documentation up-to-date.

-

If you have questions on API routes not listed in this reference, please join the Mattermost community server to ask questions in the Developers channel, or post questions to our Developer Discussion forum.

-

Bug reports in the documentation or the API are also welcome, as are pull requests to fix the issues.

-

Contributing

-

When you have answers to API questions not addressed in our documentation we ask you to consider making a pull request to improve our reference. Small changes and larger changes are all welcome.

-

We also have Help Wanted tickets 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.

-

The source code for this API reference is hosted at https://github.com/mattermost/mattermost-api-reference.

-

schema

All API access is through HTTP(S) requests at your-mattermost-url.com/api/v4. All request and response bodies are application/json.

-

When using endpoints that require a user id, the string me can be used in place of the user id to indicate the action is to be taken for the logged in user.

-

APIv3 Deprecation

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

-
    -
  1. Set your server's log level to DEBUG in System Console > General > Logging > File Log Level to print detailed logs for API requests.
    2. -
  2. 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.
      -
    • For in-house or self-built integrations, update them to use v4 with the help of this API reference. Most v3 endpoints have direct counterparts in v4 and should be migrated easily.
      • -
    • 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.
      • -
    -
    3. -
  3. 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.
    4. -
  4. 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.
    5. -
  5. Set your server's log level back to ERROR. Use the error logs to help track down any remaining uses of API v3.
    6. -
-

Below are the major changes made between v3 and v4:

-
    -
  1. Endpoint URLs only require team IDs when necessary. For example, getting a channel by ID no longer requires a team ID in v4.
    2. -
  2. Collection endpoints now generally return lists and include paging as part of the query string.
    3. -
  3. User ID is now included in most user endpoints. This allows admins to modify other users through v4 endpoints.
    4. -
-

If 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 and ask questions in the APIv4 channel.

-

drivers

The easiest way to interact with the Mattermost Web Service API is through a language specific driver.

-

Official Drivers

- -

Community-built Drivers

- -

For other community-built drivers and API wrappers, see our app directory.

-

authentication

There are multiple ways to authenticate against the Mattermost API.

-

All examples assume there is a Mattermost instance running at http://localhost:8065.

-

Session Token

-

Make an HTTP POST to your-mattermost-url.com/api/v4/users/login with a JSON body indicating the user’s login_id, password and optionally the MFA token. The login_id can be an email, username or an AD/LDAP ID depending on the system's configuration.

-
curl -i -d '{"login_id":"someone@nowhere.com","password":"thisisabadpassword"}' http://localhost:8065/api/v4/users/login

NOTE: If you're running cURL on windows, you will have to change the single quotes to double quotes, and escape the inner double quotes with backslash, like below:

-
curl -i -d "{\"login_id\":\"someone@nowhere.com\",\"password\":\"thisisabadpassword\"}" http://localhost:8065/api/v4/users/login

If successful, the response will contain a Token header and a user object in the body.

-
HTTP/1.1 200 OK
-Set-Cookie: MMSID=hyr5dmb1mbb49c44qmx4whniso; Path=/; Max-Age=2592000; HttpOnly
-Token: hyr5dmb1mbb49c44qmx4whniso
-X-Ratelimit-Limit: 10
-X-Ratelimit-Remaining: 9
-X-Ratelimit-Reset: 1
-X-Request-Id: smda55ckcfy89b6tia58shk5fh
-X-Version-Id: developer
-Date: Fri, 11 Sep 2015 13:21:14 GMT
-Content-Length: 657
-Content-Type: application/json; charset=utf-8
-
-{{user object as json}}

Include the Token as part of the Authorization header on your future API requests with the Bearer method.

-
curl -i -H 'Authorization: Bearer hyr5dmb1mbb49c44qmx4whniso' http://localhost:8065/api/v4/users/me

You should now be able to access the API as the user you logged in as.

-

Personal Access Tokens

-

Using personal access tokens is very similar to using a session token. The only real difference is that session tokens will expire, while personal access tokens will live until they are manually revoked by the user or an admin.

-

Just like session tokens, include the personal access token as part of the Authorization header in your requests using the Bearer method. Assuming our personal access token is 9xuqwrwgstrb3mzrxb83nb357a, we could use it as shown below.

-
curl -i -H 'Authorization: Bearer 9xuqwrwgstrb3mzrxb83nb357a' http://localhost:8065/api/v4/users/me

OAuth 2.0

-

Mattermost has the ability to act as an OAuth 2.0 service provider.

-

The official documentation for using your Mattermost server as an OAuth 2.0 service provider can be found here.

-

For an example on how to register an OAuth 2.0 app with your Mattermost instance, please see the Mattermost-Zapier integration documentation.

-

errors

All errors will return an appropriate HTTP response code along with the following JSON body:

-
{
-    "id": "the.error.id",
-    "message": "Something went wrong", // the reason for the error
-    "request_id": "", // the ID of the request
-    "status_code": 0, // the HTTP status code
-    "is_oauth": false // whether the error is OAuth specific
-}

rate limiting

Whenever you make an HTTP request to the Mattermost API you might notice the following headers included in the response:

-
X-Ratelimit-Limit: 10
-X-Ratelimit-Remaining: 9
-X-Ratelimit-Reset: 1441983590

These headers are telling you your current rate limit status.

- - - - - - - - - - - - - - - - - - - -
HeaderDescription
X-Ratelimit-LimitThe maximum number of requests you can make per second.
X-Ratelimit-RemainingThe number of requests remaining in the current window.
X-Ratelimit-ResetThe remaining UTC epoch seconds before the rate limit resets.
-

If you exceed your rate limit for a window you will receive the following error in the body of the response:

-
HTTP/1.1 429 Too Many Requests
-Date: Tue, 10 Sep 2015 11:20:28 GMT
-X-RateLimit-Limit: 10
-X-RateLimit-Remaining: 0
-X-RateLimit-Reset: 1
-
-limit exceeded

WebSocket

In addition to the HTTP RESTful web service, Mattermost also offers a WebSocket event delivery system and some API functionality.

-

To connect to the WebSocket follow the standard opening handshake as defined by the RFC specification to the /api/v4/websocket endpoint of Mattermost.

-

Authentication

-

The 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.

-

To authenticate with an authentication challenge, first connect the WebSocket and then send the following JSON over the connection:

-
{
-  "seq": 1,
-  "action": "authentication_challenge",
-  "data": {
-    "token": "mattermosttokengoeshere"
-  }
-}

If successful, you will receive a standard OK response over the WebSocket connection:

-
{
-  "status": "OK",
-  "seq_reply": 1
-}

Once successfully authenticated, the server will pass a hello WebSocket event containing server version over the connection.

-

Events

-

WebSocket events are primarily used to alert the client to changes in Mattermost, such as delivering new posts or alerting the client that another user is typing in a channel.

-

Events on the WebSocket will have the form:

-
{
-  "event": "hello",
-  "data": {
-    "server_version": "3.6.0.1451.1c38da627ebb4e3635677db6939e9195"
-  },
-  "broadcast":{
-    "omit_users": null,
-    "user_id": "ay5sq51sebfh58ktrce5ijtcwy",
-    "channel_id": "",
-    "team_id": ""
-  },
-  "seq": 0
-}

The event field indicates the event type, data contains any data relevant to the event and broadcast contains information about who the event was sent to. For example, the above example has user_id set to "ay5sq51sebfh58ktrce5ijtcwy" meaning that only the user with that ID received this event broadcast. The omit_users field can contain an array of user IDs that were specifically omitted from receiving the event.

-

The list of Mattermost WebSocket events are:

-
    -
  • added_to_team
    • -
  • authentication_challenge
    • -
  • channel_converted
    • -
  • channel_created
    • -
  • channel_deleted
    • -
  • channel_member_updated
    • -
  • channel_updated
    • -
  • channel_viewed
    • -
  • config_changed
    • -
  • delete_team
    • -
  • direct_added
    • -
  • emoji_added
    • -
  • ephemeral_message
    • -
  • group_added
    • -
  • hello
    • -
  • leave_team
    • -
  • license_changed
    • -
  • memberrole_updated
    • -
  • new_user
    • -
  • plugin_disabled
    • -
  • plugin_enabled
    • -
  • plugin_statuses_changed
    • -
  • post_deleted
    • -
  • post_edited
    • -
  • post_unread
    • -
  • posted
    • -
  • preference_changed
    • -
  • preferences_changed
    • -
  • preferences_deleted
    • -
  • reaction_added
    • -
  • reaction_removed
    • -
  • response
    • -
  • role_updated
    • -
  • status_change
    • -
  • typing
    • -
  • update_team
    • -
  • user_added
    • -
  • user_removed
    • -
  • user_role_updated
    • -
  • user_updated
    • -
  • dialog_opened
    • -
-

WebSocket API

-

Mattermost has some basic support for WebSocket APIs. A connected WebSocket can make requests by sending the following over the connection:

-
{
-  "action": "user_typing",
-  "seq": 2,
-  "data": {
-    "channel_id": "nhze199c4j87ped4wannrjdt9c",
-    "parent_id": ""
-  }
-}

This is an example of making a user_typing request, with the purpose of alerting the server that the connected client has begun typing in a channel or thread. The action field indicates what is being requested, and performs a similar duty as the route in a HTTP API.

-

The seq or sequence number is set by the client and should be incremented with every use. It is used to distinguish responses to requests that come down the WebSocket. For example, a standard response to the above request would be:

-
{
-  "status": "OK",
-  "seq_reply": 2
-}

Notice seq_reply is 2, matching the seq of the original request. Using this a client can distinguish which request the response is meant for.

-

If there was any information to respond with, it would be encapsulated in a data field.

-

In the case of an error, the response would be:

-
{
-  "status": "FAIL",
-  "seq_reply": 2,
-  "error": {
-    "id": "some.error.id.here",
-    "message": "Some error message here"
-  }
-}

The list of WebSocket API actions is:

-
    -
  • user_typing
    • -
  • get_statuses
    • -
  • get_statuses_by_ids
    • -
-

To see how these actions work, please refer to either the Golang WebSocket driver or our JavaScript WebSocket driver.

-

users

Endpoints for creating, getting and interacting with users.

-

When using endpoints that require a user id, the string me can be used in place of the user id to indicate the action is to be taken for the logged in user.

-

Create a user

Create a new user on the system. Password is required for email login. For other authentication types such as LDAP or SAML, auth_data and auth_service fields are required.

-
Permissions
-

No permission required but user creation can be controlled by server configuration.

-
Authorizations:
bearerAuth
query Parameters
t
string

Token id from an email invitation

-
iid
string

Token id from an invitation link

-
Request Body schema: application/json

User object to be created

-
email
required
string
username
required
string
first_name
string
last_name
string
nickname
string
auth_data
string

Service-specific authentication data, such as email address.

-
auth_service
string

The authentication service, one of "email", "gitlab", "ldap", "saml", "office365", "google", and "".

-
password
string

The password used for email authentication.

-
locale
string
props
object
notify_props
object (UserNotifyProps)

Responses

201

User creation successful

-
400

Invalid or missing parameters in URL or request body

-
403

Do not have appropriate permissions

-
post /users
http://your-mattermost-url.com/api/v4/users
https://your-mattermost-url.com/api/v4/users

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "email": "string",
  • "username": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "nickname": "string",
  • "auth_data": "string",
  • "auth_service": "string",
  • "password": "string",
  • "locale": "string",
  • "props": { },
  • "notify_props":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "username": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "nickname": "string",
  • "email": "string",
  • "email_verified": true,
  • "auth_service": "string",
  • "roles": "string",
  • "locale": "string",
  • "notify_props":
    {
    },
  • "props": { },
  • "last_password_update": 0,
  • "last_picture_update": 0,
  • "failed_attempts": 0,
  • "mfa_active": true,
  • "timezone":
    {
    },
  • "terms_of_service_id": "string",
  • "terms_of_service_create_at": 0
}

Get users

Get a page of a list of users. Based on query string parameters, select users from a team, channel, or select users not in a specific channel.

-

Since server version 4.0, some basic sorting is available using the sort query parameter. Sorting is currently only supported when selecting users on a team.

-
Permissions
-

Requires an active session and (if specified) membership to the channel or team being selected from.

-
Authorizations:
bearerAuth
query Parameters
page
integer
Default: 0

The page to select.

-
per_page
integer
Default: 60

The number of users per page. There is a maximum limit of 200 users per page.

-
in_team
string

The ID of the team to get users for.

-
not_in_team
string

The ID of the team to exclude users for. Must not be used with "in_team" query parameter.

-
in_channel
string

The ID of the channel to get users for.

-
not_in_channel
string

The ID of the channel to exclude users for. Must be used with "in_channel" query parameter.

-
group_constrained
boolean

When used with not_in_channel or not_in_team, returns only the users that are allowed to join the channel or team based on its group constrains.

-
without_team
boolean

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.

-
sort
string

Sort is only available in conjunction with certain options below. The paging parameter is also always available.

-
in_team
-

Can be "", "last_activity_at" or "create_at". -When left blank, sorting is done by username. -Minimum server version: 4.0

-
in_channel
-

Can be "", "status". -When left blank, sorting is done by username. status will sort by User's current status (Online, Away, DND, Offline), then by Username. -Minimum server version: 4.7

-

Responses

200

User page retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
get /users
http://your-mattermost-url.com/api/v4/users
https://your-mattermost-url.com/api/v4/users

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-
-// page, perPage, etag
-users := Client.GetUsers(0, 60, "")
-users = Client.GetUsersInChannel("channelid", 0, 60, "")
-users = Client.GetUsersNotInChannel("teamid", "channelid", 0, 60, "")
-users = Client.GetUsersInTeam("teamid", 0, 60, "")
-users = Client.GetUsersNotInTeam("teamid", 0, 60, "")
-users = Client.GetUsersWithoutTeam(0, 60, "")
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Get users by ids

Get a list of users based on a provided list of user ids.

-
Permissions
-

Requires an active session but no other permissions.

-
Authorizations:
bearerAuth
query Parameters
since
integer

Only return users that have been modified since the given Unix timestamp (in milliseconds).

-

Minimum server version: 5.14

-
Request Body schema: application/json

List of user ids

-
Array
string

Responses

200

User list retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
post /users/ids
http://your-mattermost-url.com/api/v4/users/ids
https://your-mattermost-url.com/api/v4/users/ids

Request samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • "string"
]

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Get users by group channels ids

Get an object containing a key per group channel id in the -query and its value as a list of users members of that group -channel.

-

The user must be a member of the group ids in the query, or -they will be omitted from the response.

-
Permissions
-

Requires an active session but no other permissions.

-

Minimum server version: 5.14

-
Authorizations:
bearerAuth
Request Body schema: application/json

List of group channel ids

-
Array
string

Responses

200

User list retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
post /users/group_channels
http://your-mattermost-url.com/api/v4/users/group_channels
https://your-mattermost-url.com/api/v4/users/group_channels

Request samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • "string"
]

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "<CHANNEL_ID>":
    [
    ]
}

Get users by usernames

Get a list of users based on a provided list of usernames.

-
Permissions
-

Requires an active session but no other permissions.

-
Authorizations:
bearerAuth
Request Body schema: application/json

List of usernames

-
Array
string

Responses

200

User list retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
post /users/usernames
http://your-mattermost-url.com/api/v4/users/usernames
https://your-mattermost-url.com/api/v4/users/usernames

Request samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • "string"
]

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Search users

Get a list of users based on search criteria provided in the request body. Searches are typically done against username, full name, nickname and email unless otherwise configured by the server.

-
Permissions
-

Requires an active session and read_channel and/or view_team permissions for any channels or teams specified in the request body.

-
Authorizations:
bearerAuth
Request Body schema: application/json

Search criteria

-
term
required
string

The term to match against username, full name, nickname and email

-
team_id
string

If provided, only search users on this team

-
not_in_team_id
string

If provided, only search users not on this team

-
in_channel_id
string

If provided, only search users in this channel

-
not_in_channel_id
string

If provided, only search users not in this channel. Must specifiy team_id when using this option

-
group_constrained
boolean

When used with not_in_channel_id or not_in_team_id, returns only the users that are allowed to join the channel or team based on its group constrains.

-
allow_inactive
boolean

When true, include deactivated users in the results

-
without_team
boolean

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
integer
Default: 100

The maximum number of users to return in the results

-

Available as of server version 5.6. Defaults to 100 if not provided or on an earlier server version.

-

Responses

200

User list retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
post /users/search
http://your-mattermost-url.com/api/v4/users/search
https://your-mattermost-url.com/api/v4/users/search

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "term": "string",
  • "team_id": "string",
  • "not_in_team_id": "string",
  • "in_channel_id": "string",
  • "not_in_channel_id": "string",
  • "group_constrained": true,
  • "allow_inactive": true,
  • "without_team": true,
  • "limit": 100
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Autocomplete users

Get a list of users for the purpose of autocompleting based on the provided search term. Specify a combination of team_id and channel_id to filter results further.

-
Permissions
-

Requires an active session and view_team and read_channel on any teams or channels used to filter the results further.

-
Authorizations:
bearerAuth
query Parameters
team_id
string

Team ID

-
channel_id
string

Channel ID

-
name
required
string

Username, nickname first name or last name

-
limit
integer
Default: 100

The maximum number of users to return in each subresult

-

Available as of server version 5.6. Defaults to 100 if not provided or on an earlier server version.

-

Responses

200

User autocomplete successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
get /users/autocomplete
http://your-mattermost-url.com/api/v4/users/autocomplete
https://your-mattermost-url.com/api/v4/users/autocomplete

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-teamID := "4xp9fdt77pncbef59f4k1qe83o"
-channelID := "Ej3SKOHlWIKAblkUTK5Xvkj2cm"
-username := "testUsername"
-
-users, resp := Client.AutocompleteUsersInChannel(teamID, channelID, username, 100, "")
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "users":
    [
    ],
  • "out_of_channel":
    [
    ]
}

Get total count of users in the system

Get a total count of users in the system.

-
Permissions
-

Must be authenticated.

-
Authorizations:
bearerAuth

Responses

200

User stats retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
get /users/stats
http://your-mattermost-url.com/api/v4/users/stats
https://your-mattermost-url.com/api/v4/users/stats

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-stats, resp := Client.GetTotalUsersStats("")
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "total_users_count": 0
}

Get a user

Get a user a object. Sensitive information will be sanitized out.

-
Permissions
-

Requires an active session but no other permissions.

-
Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

-

Responses

200

User retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
404

Resource not found

-
get /users/{user_id}
http://your-mattermost-url.com/api/v4/users/{user_id}
https://your-mattermost-url.com/api/v4/users/{user_id}

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-userID := "4xp9fdt77pncbef59f4k1qe83o"
-
-user, resp := Client.GetUser(userID, "")
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "username": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "nickname": "string",
  • "email": "string",
  • "email_verified": true,
  • "auth_service": "string",
  • "roles": "string",
  • "locale": "string",
  • "notify_props":
    {
    },
  • "props": { },
  • "last_password_update": 0,
  • "last_picture_update": 0,
  • "failed_attempts": 0,
  • "mfa_active": true,
  • "timezone":
    {
    },
  • "terms_of_service_id": "string",
  • "terms_of_service_create_at": 0
}

Update a user

Update a user by providing the user object. The fields that can be updated are defined in the request body, all other provided fields will be ignored. Any fields not included in the request body will be set to null or reverted to default values.

-
Permissions
-

Must be logged in as the user being updated or have the edit_other_users permission.

-
Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

-
Request Body schema: application/json

User object that is to be updated

-
id
required
string
email
string
username
string
first_name
string
last_name
string
nickname
string
locale
string
position
string
props
object
notify_props
object (UserNotifyProps)

Responses

200

User update successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
put /users/{user_id}
http://your-mattermost-url.com/api/v4/users/{user_id}
https://your-mattermost-url.com/api/v4/users/{user_id}

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "email": "string",
  • "username": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "nickname": "string",
  • "locale": "string",
  • "position": "string",
  • "props": { },
  • "notify_props":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "username": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "nickname": "string",
  • "email": "string",
  • "email_verified": true,
  • "auth_service": "string",
  • "roles": "string",
  • "locale": "string",
  • "notify_props":
    {
    },
  • "props": { },
  • "last_password_update": 0,
  • "last_picture_update": 0,
  • "failed_attempts": 0,
  • "mfa_active": true,
  • "timezone":
    {
    },
  • "terms_of_service_id": "string",
  • "terms_of_service_create_at": 0
}

Deactivate a user account.

Deactivates the user and revokes all its sessions by archiving its user object.

-
Permissions
-

Must be logged in as the user being deactivated or have the edit_other_users permission.

-
Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

-

Responses

200

User deactivation successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
delete /users/{user_id}
http://your-mattermost-url.com/api/v4/users/{user_id}
https://your-mattermost-url.com/api/v4/users/{user_id}

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-userID := "4xp9fdt77pncbef59f4k1qe83o"
-
-ok, resp := Client.DeleteUser(userID)
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Patch a user

Partially update a user by providing only the fields you want to update. Omitted fields will not be updated. The fields that can be updated are defined in the request body, all other provided fields will be ignored.

-
Permissions
-

Must be logged in as the user being updated or have the edit_other_users permission.

-
Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

-
Request Body schema: application/json

User object that is to be updated

-
email
string
username
string
first_name
string
last_name
string
nickname
string
locale
string
position
string
props
object
notify_props
object (UserNotifyProps)

Responses

200

User patch successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
put /users/{user_id}/patch
http://your-mattermost-url.com/api/v4/users/{user_id}/patch
https://your-mattermost-url.com/api/v4/users/{user_id}/patch

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "email": "string",
  • "username": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "nickname": "string",
  • "locale": "string",
  • "position": "string",
  • "props": { },
  • "notify_props":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "username": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "nickname": "string",
  • "email": "string",
  • "email_verified": true,
  • "auth_service": "string",
  • "roles": "string",
  • "locale": "string",
  • "notify_props":
    {
    },
  • "props": { },
  • "last_password_update": 0,
  • "last_picture_update": 0,
  • "failed_attempts": 0,
  • "mfa_active": true,
  • "timezone":
    {
    },
  • "terms_of_service_id": "string",
  • "terms_of_service_create_at": 0
}

Update a user's roles

Update a user's system-level roles. Valid user roles are "system_user", "system_admin" or both of them. Overwrites any previously assigned system-level roles.

-
Permissions
-

Must have the manage_roles permission.

-
Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

-
Request Body schema: application/json

Space-delimited system roles to assign to the user

-
roles
required
string

Responses

200

User roles update successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
put /users/{user_id}/roles
http://your-mattermost-url.com/api/v4/users/{user_id}/roles
https://your-mattermost-url.com/api/v4/users/{user_id}/roles

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "roles": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Update user active status

Update user active or inactive status.

-

Since server version 4.6, users using a SSO provider to login can be activated or deactivated with this endpoint. However, if their activation status in Mattermost does not reflect their status in the SSO provider, the next synchronization or login by that user will reset the activation status to that of their account in the SSO provider. Server versions 4.5 and before do not allow activation or deactivation of SSO users from this endpoint.

-
Permissions
-

User can deactivate themselves. -User with manage_system permission can activate or deactivate a user.

-
Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

-
Request Body schema: application/json

Use true to set the user active, false for inactive

-
active
required
boolean

Responses

200

User active status update successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
put /users/{user_id}/active
http://your-mattermost-url.com/api/v4/users/{user_id}/active
https://your-mattermost-url.com/api/v4/users/{user_id}/active

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "active": true
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Get user's profile image

Get a user's profile image based on user_id string parameter.

-
Permissions
-

Must be logged in.

-
Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

-

Responses

200

User's profile image

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
501

Feature is disabled

-
get /users/{user_id}/image
http://your-mattermost-url.com/api/v4/users/{user_id}/image
https://your-mattermost-url.com/api/v4/users/{user_id}/image

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-userID := "4xp9fdt77pncbef59f4k1qe83o"
-
-data, resp := Client.GetProfileImage(userID, "")
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

Set user's profile image

Set a user's profile image based on user_id string parameter.

-
Permissions
-

Must be logged in as the user being updated or have the edit_other_users permission.

-
Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

-
Request Body schema: multipart/form-data
image
required
string <binary>

The image to be uploaded

-

Responses

200

Profile image set successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
501

Feature is disabled

-
post /users/{user_id}/image
http://your-mattermost-url.com/api/v4/users/{user_id}/image
https://your-mattermost-url.com/api/v4/users/{user_id}/image

Request samples

Copy
import (
-  "io/ioutil"
-  "log"
-
-  "github.com/mattermost/mattermost-server/model"
-)
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-data, err := ioutil.ReadFile("profile_pic.png")
-if err != nil {
-  log.Fatal(err)
-}
-
-userID := "4xp9fdt77pncbef59f4k1qe83o"
-
-ok, resp := Client.SetProfileImage(userID, data)
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Delete user's profile image

Delete user's profile image and reset to default image based on user_id string parameter.

-
Permissions
-

Must be logged in as the user being updated or have the edit_other_users permission. -Minimum server version: 5.5

-
Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

-

Responses

200

Profile image reset successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
501

Feature is disabled

-
delete /users/{user_id}/image
http://your-mattermost-url.com/api/v4/users/{user_id}/image
https://your-mattermost-url.com/api/v4/users/{user_id}/image

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-userID := "4xp9fdt77pncbef59f4k1qe83o"
-
-// Deleting user's profile image consists on resetting it to default one
-ok, resp := Client.SetDefaultProfileImage(userID)
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Return user's default (generated) profile image

Returns the default (generated) user profile image based on user_id string parameter.

-
Permissions
-

Must be logged in. -Minimum server version: 5.5

-
Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

-

Responses

200

Default profile image

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
501

Feature is disabled

-
get /users/{user_id}/image/default
http://your-mattermost-url.com/api/v4/users/{user_id}/image/default
https://your-mattermost-url.com/api/v4/users/{user_id}/image/default

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-userID := "4xp9fdt77pncbef59f4k1qe83o"
-
-ok, resp := Client.SetDefaultProfileImage(userID)
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

Get a user by username

Get a user object by providing a username. Sensitive information will be sanitized out.

-
Permissions
-

Requires an active session but no other permissions.

-
Authorizations:
bearerAuth
path Parameters
username
required
string

Username

-

Responses

200

User retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
404

Resource not found

-
get /users/username/{username}
http://your-mattermost-url.com/api/v4/users/username/{username}
https://your-mattermost-url.com/api/v4/users/username/{username}

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-userID := "4xp9fdt77pncbef59f4k1qe83o"
-
-user, resp := Client.GetUserByUsername(userID, "")
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "username": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "nickname": "string",
  • "email": "string",
  • "email_verified": true,
  • "auth_service": "string",
  • "roles": "string",
  • "locale": "string",
  • "notify_props":
    {
    },
  • "props": { },
  • "last_password_update": 0,
  • "last_picture_update": 0,
  • "failed_attempts": 0,
  • "mfa_active": true,
  • "timezone":
    {
    },
  • "terms_of_service_id": "string",
  • "terms_of_service_create_at": 0
}

Reset password

Update the password for a user using a one-use, timed recovery code tied to the user's account. Only works for non-SSO users.

-
Permissions
-

No permissions required.

-
Authorizations:
bearerAuth
Request Body schema: application/json
code
required
string

The recovery code

-
new_password
required
string

The new password for the user

-

Responses

200

User password update successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
post /users/password/reset
http://your-mattermost-url.com/api/v4/users/password/reset
https://your-mattermost-url.com/api/v4/users/password/reset

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "code": "string",
  • "new_password": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Update a user's MFA

Activates multi-factor authentication for the user if activate is true and a valid code is provided. If activate is false, then code is not required and multi-factor authentication is disabled for the user.

-
Permissions
-

Must be logged in as the user being updated or have the edit_other_users permission.

-
Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

-
Request Body schema: application/json
activate
required
boolean

Use true to activate, false to deactivate

-
code
string

The code produced by your MFA client. Required if activate is true

-

Responses

200

User MFA update successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
501

Feature is disabled

-
put /users/{user_id}/mfa
http://your-mattermost-url.com/api/v4/users/{user_id}/mfa
https://your-mattermost-url.com/api/v4/users/{user_id}/mfa

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "activate": true,
  • "code": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Generate MFA secret

Generates an multi-factor authentication secret for a user and returns it as a string and as base64 encoded QR code image.

-
Permissions
-

Must be logged in as the user or have the edit_other_users permission.

-
Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

-

Responses

200

MFA secret generation successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
501

Feature is disabled

-
post /users/{user_id}/mfa/generate
http://your-mattermost-url.com/api/v4/users/{user_id}/mfa/generate
https://your-mattermost-url.com/api/v4/users/{user_id}/mfa/generate

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-userID := "BbaYBYDV5IDOZFiJGBSzkw1k5u"
-
-mfaSecret, resp = Client.GenerateMfaSecret(userID)
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "secret": "string",
  • "qr_code": "string"
}

Demote a user to a guest

Convert a regular user into a guest. This will convert the user into a -guest for the whole system while retaining their existing team and -channel memberships.

-

Minimum server version: 5.16

-
Permissions
-

Must be logged in as the user or have the demote_to_guest permission.

-
Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

-

Responses

200

User successfully demoted

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
501

Feature is disabled

-
post /users/{user_id}/demote
http://your-mattermost-url.com/api/v4/users/{user_id}/demote
https://your-mattermost-url.com/api/v4/users/{user_id}/demote

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-userID := "BbaYBYDV5IDOZFiJGBSzkw1k5u"
-
-ok, resp = Client.demoteUserToGuest(userID)
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Promote a guest to user

Convert a guest into a regular user. This will convert the guest into a -user for the whole system while retaining any team and channel -memberships and automatically joining them to the default channels.

-

Minimum server version: 5.16

-
Permissions
-

Must be logged in as the user or have the promote_guest permission.

-
Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

-

Responses

200

Guest successfully promoted

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
501

Feature is disabled

-
post /users/{user_id}/promote
http://your-mattermost-url.com/api/v4/users/{user_id}/promote
https://your-mattermost-url.com/api/v4/users/{user_id}/promote

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-userID := "BbaYBYDV5IDOZFiJGBSzkw1k5u"
-
-ok, resp = Client.PromoteGuestToUser(userID)
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Check MFA

Check if a user has multi-factor authentication active on their account by providing a login id. Used to check whether an MFA code needs to be provided when logging in.

-
Permissions
-

No permission required.

-
Authorizations:
bearerAuth
Request Body schema: application/json
login_id
required
string

The email or username used to login

-

Responses

200

MFA check successful

-
400

Invalid or missing parameters in URL or request body

-
post /users/mfa
http://your-mattermost-url.com/api/v4/users/mfa
https://your-mattermost-url.com/api/v4/users/mfa

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "login_id": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "mfa_required": true
}

Update a user's password

Update a user's password. New password must meet password policy set by server configuration. Current password is required if you're updating your own password.

-
Permissions
-

Must be logged in as the user the password is being changed for or have manage_system permission.

-
Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

-
Request Body schema: application/json
current_password
string

The current password for the user

-
new_password
required
string

The new password for the user

-

Responses

200

User password update successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
put /users/{user_id}/password
http://your-mattermost-url.com/api/v4/users/{user_id}/password
https://your-mattermost-url.com/api/v4/users/{user_id}/password

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "current_password": "string",
  • "new_password": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Send password reset email

Send an email containing a link for resetting the user's password. The link will contain a one-use, timed recovery code tied to the user's account. Only works for non-SSO users.

-
Permissions
-

No permissions required.

-
Authorizations:
bearerAuth
Request Body schema: application/json
email
required
string

The email of the user

-

Responses

200

Email sent if account exists

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
post /users/password/reset/send
http://your-mattermost-url.com/api/v4/users/password/reset/send
https://your-mattermost-url.com/api/v4/users/password/reset/send

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "email": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Get a user by email

Get a user object by providing a user email. Sensitive information will be sanitized out.

-
Permissions
-

Requires an active session and for the current session to be able to view another user's email based on the server's privacy settings.

-
Authorizations:
bearerAuth
path Parameters
email
required
string

User Email

-

Responses

200

User retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
get /users/email/{email}
http://your-mattermost-url.com/api/v4/users/email/{email}
https://your-mattermost-url.com/api/v4/users/email/{email}

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-email := "test@domain.com"
-
-user, resp := Client.GetUserByEmail(email, "")
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "username": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "nickname": "string",
  • "email": "string",
  • "email_verified": true,
  • "auth_service": "string",
  • "roles": "string",
  • "locale": "string",
  • "notify_props":
    {
    },
  • "props": { },
  • "last_password_update": 0,
  • "last_picture_update": 0,
  • "failed_attempts": 0,
  • "mfa_active": true,
  • "timezone":
    {
    },
  • "terms_of_service_id": "string",
  • "terms_of_service_create_at": 0
}

Get user's sessions

Get a list of sessions by providing the user GUID. Sensitive information will be sanitized out.

-
Permissions
-

Must be logged in as the user being updated or have the edit_other_users permission.

-
Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

-

Responses

200

User session retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
get /users/{user_id}/sessions
http://your-mattermost-url.com/api/v4/users/{user_id}/sessions
https://your-mattermost-url.com/api/v4/users/{user_id}/sessions

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-userID := "zWEyrTZ7GZ22aBSfoX60iWryTY"
-
-sessions, resp := Client.GetSessions(userID, "")
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Revoke a user session

Revokes a user session from the provided user id and session id strings.

-
Permissions
-

Must be logged in as the user being updated or have the edit_other_users permission.

-
Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

-
Request Body schema: application/json
session_id
required
string

The session GUID to revoke.

-

Responses

200

User session revoked successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
post /users/{user_id}/sessions/revoke
http://your-mattermost-url.com/api/v4/users/{user_id}/sessions/revoke
https://your-mattermost-url.com/api/v4/users/{user_id}/sessions/revoke

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "session_id": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Revoke all active sessions for a user

Revokes all user sessions from the provided user id and session id strings.

-
Permissions
-

Must be logged in as the user being updated or have the edit_other_users permission. -Minimum server version: 4.4

-
Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

-

Responses

200

User sessions revoked successfully

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
post /users/{user_id}/sessions/revoke/all
http://your-mattermost-url.com/api/v4/users/{user_id}/sessions/revoke/all
https://your-mattermost-url.com/api/v4/users/{user_id}/sessions/revoke/all

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-userID := "zWEyrTZ7GZ22aBSfoX60iWryTY"
-
-ok, resp := Client.RevokeAllSessions(userID)
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Attach mobile device

Attach a mobile device id to the currently logged in session. This will enable push notifications for a user, if configured by the server.

-
Permissions
-

Must be authenticated.

-
Authorizations:
bearerAuth
Request Body schema: application/json
device_id
required
string

Mobile device id. For Android prefix the id with android: and Apple with apple:

-

Responses

200

Device id attach successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
put /users/sessions/device
http://your-mattermost-url.com/api/v4/users/sessions/device
https://your-mattermost-url.com/api/v4/users/sessions/device

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "device_id": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Get user's audits

Get a list of audit by providing the user GUID.

-
Permissions
-

Must be logged in as the user or have the edit_other_users permission.

-
Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

-

Responses

200

User audits retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
get /users/{user_id}/audits
http://your-mattermost-url.com/api/v4/users/{user_id}/audits
https://your-mattermost-url.com/api/v4/users/{user_id}/audits

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-userID := "zWEyrTZ7GZ22aBSfoX60iWryTY"
-
-audits, resp := Client.GetUserAudits(userID, 0, 100, "")
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Verify user email

Verify the email used by a user to sign-up their account with.

-
Permissions
-

No permissions required.

-
Authorizations:
bearerAuth
Request Body schema: application/json
token
required
string

The token given to validate the email

-

Responses

200

User email verification successful

-
400

Invalid or missing parameters in URL or request body

-
post /users/email/verify
http://your-mattermost-url.com/api/v4/users/email/verify
https://your-mattermost-url.com/api/v4/users/email/verify

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "token": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Send verification email

Send an email with a verification link to a user that has an email matching the one in the request body. This endpoint will return success even if the email does not match any users on the system.

-
Permissions
-

No permissions required.

-
Authorizations:
bearerAuth
Request Body schema: application/json
email
required
string

Email of a user

-

Responses

200

Email send successful if email exists

-
400

Invalid or missing parameters in URL or request body

-
post /users/email/verify/send
http://your-mattermost-url.com/api/v4/users/email/verify/send
https://your-mattermost-url.com/api/v4/users/email/verify/send

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "email": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Switch login method

Switch a user's login method from using email to OAuth2/SAML/LDAP or back to email. When switching to OAuth2/SAML, account switching is not complete until the user follows the returned link and completes any steps on the OAuth2/SAML service provider.

-

To switch from email to OAuth2/SAML, specify current_service, new_service, email and password.

-

To switch from OAuth2/SAML to email, specify current_service, new_service, email and new_password.

-

To switch from email to LDAP/AD, specify current_service, new_service, email, password, ldap_ip and new_password (this is the user's LDAP password).

-

To switch from LDAP/AD to email, specify current_service, new_service, ldap_ip, password (this is the user's LDAP password), email and new_password.

-

Additionally, specify mfa_code when trying to switch an account on LDAP/AD or email that has MFA activated.

-
Permissions
-

No current authentication required except when switching from OAuth2/SAML to email.

-
Authorizations:
bearerAuth
Request Body schema: application/json
current_service
required
string

The service the user currently uses to login

-
new_service
required
string

The service the user will use to login

-
email
string

The email of the user

-
password
string

The password used with the current service

-
mfa_code
string

The MFA code of the current service

-
ldap_id
string

The LDAP/AD id of the user

-

Responses

200

Login method switch or request successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
501

Feature is disabled

-
post /users/login/switch
http://your-mattermost-url.com/api/v4/users/login/switch
https://your-mattermost-url.com/api/v4/users/login/switch

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "current_service": "string",
  • "new_service": "string",
  • "email": "string",
  • "password": "string",
  • "mfa_code": "string",
  • "ldap_id": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "follow_link": "string"
}

Create a user access token

Generate a user access token that can be used to authenticate with the Mattermost REST API.

-

Minimum server version: 4.1

-
Permissions
-

Must have create_user_access_token permission. For non-self requests, must also have the edit_other_users permission.

-
Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

-
Request Body schema: application/json
description
required
string

A description of the token usage

-

Responses

201

User access token creation successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
post /users/{user_id}/tokens
http://your-mattermost-url.com/api/v4/users/{user_id}/tokens
https://your-mattermost-url.com/api/v4/users/{user_id}/tokens

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "description": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "token": "string",
  • "user_id": "string",
  • "description": "string"
}

Get user access tokens

Get a list of user access tokens for a user. Does not include the actual authentication tokens. Use query parameters for paging.

-

Minimum server version: 4.1

-
Permissions
-

Must have read_user_access_token permission. For non-self requests, must also have the edit_other_users permission.

-
Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

-
query Parameters
page
integer
Default: 0

The page to select.

-
per_page
integer
Default: 60

The number of tokens per page.

-

Responses

200

User access tokens retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
get /users/{user_id}/tokens
http://your-mattermost-url.com/api/v4/users/{user_id}/tokens
https://your-mattermost-url.com/api/v4/users/{user_id}/tokens

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-userID := "adWv1qPZmHdtxk7Lmqh6RtxWxS"
-
-tokens, resp := Client.GetUserAccessTokensForUser(userID, 0, 100)
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Get user access tokens

Get a page of user access tokens for users on the system. Does not include the actual authentication tokens. Use query parameters for paging.

-

Minimum server version: 4.7

-
Permissions
-

Must have manage_system permission.

-
Authorizations:
bearerAuth
query Parameters
page
integer
Default: 0

The page to select.

-
per_page
integer
Default: 60

The number of tokens per page.

-

Responses

200

User access tokens retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
get /users/tokens
http://your-mattermost-url.com/api/v4/users/tokens
https://your-mattermost-url.com/api/v4/users/tokens

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-tokens, resp := Client.GetUserAccessTokens(0, 100)
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Revoke a user access token

Revoke a user access token and delete any sessions using the token.

-

Minimum server version: 4.1

-
Permissions
-

Must have revoke_user_access_token permission. For non-self requests, must also have the edit_other_users permission.

-
Authorizations:
bearerAuth
Request Body schema: application/json
token_id
required
string

The user access token GUID to revoke

-

Responses

200

User access token revoke successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
post /users/tokens/revoke
http://your-mattermost-url.com/api/v4/users/tokens/revoke
https://your-mattermost-url.com/api/v4/users/tokens/revoke

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "token_id": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Get a user access token

Get a user access token. Does not include the actual authentication token.

-

Minimum server version: 4.1

-
Permissions
-

Must have read_user_access_token permission. For non-self requests, must also have the edit_other_users permission.

-
Authorizations:
bearerAuth
path Parameters
token_id
required
string

User access token GUID

-

Responses

200

User access token retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
get /users/tokens/{token_id}
http://your-mattermost-url.com/api/v4/users/tokens/{token_id}
https://your-mattermost-url.com/api/v4/users/tokens/{token_id}

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-tokenID := "adWv1qPZmHdtxk7Lmqh6RtxWxS"
-
-token, resp := Client.GetUserAccessToken(tokenID)
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "user_id": "string",
  • "description": "string",
  • "is_active": true
}

Disable personal access token

Disable a personal access token and delete any sessions using the token. The token can be re-enabled using /users/tokens/enable.

-

Minimum server version: 4.4

-
Permissions
-

Must have revoke_user_access_token permission. For non-self requests, must also have the edit_other_users permission.

-
Authorizations:
bearerAuth
Request Body schema: application/json
token_id
required
string

The personal access token GUID to disable

-

Responses

200

Personal access token disable successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
post /users/tokens/disable
http://your-mattermost-url.com/api/v4/users/tokens/disable
https://your-mattermost-url.com/api/v4/users/tokens/disable

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "token_id": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Enable personal access token

Re-enable a personal access token that has been disabled.

-

Minimum server version: 4.4

-
Permissions
-

Must have create_user_access_token permission. For non-self requests, must also have the edit_other_users permission.

-
Authorizations:
bearerAuth
Request Body schema: application/json
token_id
required
string

The personal access token GUID to enable

-

Responses

200

Personal access token enable successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
post /users/tokens/enable
http://your-mattermost-url.com/api/v4/users/tokens/enable
https://your-mattermost-url.com/api/v4/users/tokens/enable

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "token_id": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Search tokens

Get a list of tokens based on search criteria provided in the request body. Searches are done against the token id, user id and username.

-

Minimum server version: 4.7

-
Permissions
-

Must have manage_system permission.

-
Authorizations:
bearerAuth
Request Body schema: application/json

Search criteria

-
term
required
string

The search term to match against the token id, user id or username.

-

Responses

200

Personal access token search successful

-
post /users/tokens/search
http://your-mattermost-url.com/api/v4/users/tokens/search
https://your-mattermost-url.com/api/v4/users/tokens/search

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "term": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Update a user's authentication method

Updates a user's authentication method. This can be used to change them to/from LDAP authentication for example.

-

Minimum server version: 4.6

-
Permissions
-

Must have the edit_other_users permission.

-
Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

-
Request Body schema: application/json
auth_data
string

Service-specific authentication data

-
auth_service
string

The authentication service such as "email", "gitlab", or "ldap"

-
password
string

The password used for email authentication

-

Responses

200

User auth update successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
501

Feature is disabled

-
put /users/{user_id}/auth
http://your-mattermost-url.com/api/v4/users/{user_id}/auth
https://your-mattermost-url.com/api/v4/users/{user_id}/auth

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "auth_data": "string",
  • "auth_service": "string",
  • "password": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "auth_data": "string",
  • "auth_service": "string",
  • "password": "string"
}

Records user action when they accept or decline custom terms of service

Records user action when they accept or decline custom terms of service. Records the action in audit table. -Updates user's last accepted terms of service ID if they accepted it.

-

Minimum server version: 5.4

-
Permissions
-

Must be logged in as the user being acted on.

-
Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

-
Request Body schema: application/json

terms of service details

-
serviceTermsId
required
string

terms of service ID on which the user is acting on

-
accepted
required
string

true or false, indicates whether the user accepted or rejected the terms of service.

-

Responses

200

Terms of service action recorded successfully

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
post /users/{user_id}/terms_of_service
http://your-mattermost-url.com/api/v4/users/{user_id}/terms_of_service
https://your-mattermost-url.com/api/v4/users/{user_id}/terms_of_service

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "serviceTermsId": "string",
  • "accepted": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Fetches user's latest terms of service action if the latest action was for acceptance.

Will be deprecated in v6.0 -Fetches user's latest terms of service action if the latest action was for acceptance.

-

Minimum server version: 5.6

-
Permissions
-

Must be logged in as the user being acted on.

-
Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

-

Responses

200

User's accepted terms of service action

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
404

User hasn't performed an action or the latest action was a rejection.

-
get /users/{user_id}/terms_of_service
http://your-mattermost-url.com/api/v4/users/{user_id}/terms_of_service
https://your-mattermost-url.com/api/v4/users/{user_id}/terms_of_service

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-userID := "adWv1qPZmHdtxk7Lmqh6RtxWxS"
-
-userTermsOfService, resp := Client.GetUserTermsOfService(userID, "")
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "user_id": "string",
  • "terms_of_service_id": "string",
  • "create_at": 0
}

Revoke all sessions from all users.

For any session currently on the server (including admin) it will be revoked. -Clients will be notified to log out users.

-

Minimum server version: 5.14

-
Permissions
-

Must have manage_system permission.

-
Authorizations:
bearerAuth

Responses

200

Sessions successfully revoked.

-
401

No access token provided

-
403

Do not have appropriate permissions

-
post /users/sessions/revoke/all
http://your-mattermost-url.com/api/v4/users/sessions/revoke/all
https://your-mattermost-url.com/api/v4/users/sessions/revoke/all

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-response, err := Client.RevokeSessionsFromAllUsers()
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

bots

Endpoints for creating, getting and updating bot users.

-

Create a bot

Create a new bot account on the system. Username is required.

-
Permissions
-

Must have create_bot permission. -Minimum server version: 5.10

-
Authorizations:
bearerAuth
Request Body schema: application/json

Bot to be created

-
username
required
string
display_name
string
description
string

Responses

201

Bot creation successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
post /bots
http://your-mattermost-url.com/api/v4/bots
https://your-mattermost-url.com/api/v4/bots

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "username": "string",
  • "display_name": "string",
  • "description": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "user_id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "username": "string",
  • "display_name": "string",
  • "description": "string",
  • "owner_id": "string"
}

Get bots

Get a page of a list of bots.

-
Permissions
-

Must have read_bots permission for bots you are managing, and read_others_bots permission for bots others are managing. -Minimum server version: 5.10

-
Authorizations:
bearerAuth
query Parameters
page
integer
Default: 0

The page to select.

-
per_page
integer
Default: 60

The number of users per page. There is a maximum limit of 200 users per page.

-
include_deleted
boolean

If deleted bots should be returned.

-
only_orphaned
boolean

When true, only orphaned bots will be returned. A bot is consitered orphaned if it's owner has been deactivated.

-

Responses

200

Bot page retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
get /bots
http://your-mattermost-url.com/api/v4/bots
https://your-mattermost-url.com/api/v4/bots

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Patch a bot

Partially update a bot by providing only the fields you want to update. Omitted fields will not be updated. The fields that can be updated are defined in the request body, all other provided fields will be ignored.

-
Permissions
-

Must have manage_bots permission. -Minimum server version: 5.10

-
Authorizations:
bearerAuth
path Parameters
bot_user_id
required
string

Bot user ID

-
Request Body schema: application/json

Bot to be created

-
username
required
string
display_name
string
description
string

Responses

200

Bot patch successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
put /bots/{bot_user_id}
http://your-mattermost-url.com/api/v4/bots/{bot_user_id}
https://your-mattermost-url.com/api/v4/bots/{bot_user_id}

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "username": "string",
  • "display_name": "string",
  • "description": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "user_id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "username": "string",
  • "display_name": "string",
  • "description": "string",
  • "owner_id": "string"
}

Get a bot

Get a bot specified by its bot id.

-
Permissions
-

Must have read_bots permission for bots you are managing, and read_others_bots permission for bots others are managing. -Minimum server version: 5.10

-
Authorizations:
bearerAuth
path Parameters
bot_user_id
required
string

Bot user ID

-
query Parameters
include_deleted
boolean

If deleted bots should be returned.

-

Responses

200

Bot successfully retrieved.

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
get /bots/{bot_user_id}
http://your-mattermost-url.com/api/v4/bots/{bot_user_id}
https://your-mattermost-url.com/api/v4/bots/{bot_user_id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "user_id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "username": "string",
  • "display_name": "string",
  • "description": "string",
  • "owner_id": "string"
}

Disable a bot

Disable a bot.

-
Permissions
-

Must have manage_bots permission. -Minimum server version: 5.10

-
Authorizations:
bearerAuth
path Parameters
bot_user_id
required
string

Bot user ID

-

Responses

200

Bot successfully disabled.

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
post /bots/{bot_user_id}/disable
http://your-mattermost-url.com/api/v4/bots/{bot_user_id}/disable
https://your-mattermost-url.com/api/v4/bots/{bot_user_id}/disable

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "user_id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "username": "string",
  • "display_name": "string",
  • "description": "string",
  • "owner_id": "string"
}

Enable a bot

Enable a bot.

-
Permissions
-

Must have manage_bots permission. -Minimum server version: 5.10

-
Authorizations:
bearerAuth
path Parameters
bot_user_id
required
string

Bot user ID

-

Responses

200

Bot successfully enabled.

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
post /bots/{bot_user_id}/enable
http://your-mattermost-url.com/api/v4/bots/{bot_user_id}/enable
https://your-mattermost-url.com/api/v4/bots/{bot_user_id}/enable

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "user_id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "username": "string",
  • "display_name": "string",
  • "description": "string",
  • "owner_id": "string"
}

Assign a bot to a user

Assign a bot to a specified user.

-
Permissions
-

Must have manage_bots permission. -Minimum server version: 5.10

-
Authorizations:
bearerAuth
path Parameters
bot_user_id
required
string

Bot user ID

-
user_id
required
string

The user ID to assign the bot to.

-

Responses

200

Bot successfully assigned.

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
post /bots/{bot_user_id}/assign/{user_id}
http://your-mattermost-url.com/api/v4/bots/{bot_user_id}/assign/{user_id}
https://your-mattermost-url.com/api/v4/bots/{bot_user_id}/assign/{user_id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "user_id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "username": "string",
  • "display_name": "string",
  • "description": "string",
  • "owner_id": "string"
}

Get bot's LHS icon

Get a bot's LHS icon image based on bot_user_id string parameter.

-
Permissions
-

Must be logged in. -Minimum server version: 5.14

-
Authorizations:
bearerAuth
path Parameters
bot_user_id
required
string

Bot user ID

-

Responses

200

Bot's LHS icon image

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
500

Something went wrong with the server

-
501

Feature is disabled

-
get /bots/{bot_user_id}/icon
http://your-mattermost-url.com/api/v4/bots/{bot_user_id}/icon
https://your-mattermost-url.com/api/v4/bots/{bot_user_id}/icon

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-botUserID := "4xp9fdt77pncbef59f4k1qe83o"
-
-data, resp := Client.GetBotIconImage(botUserID)
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

Set bot's LHS icon image

Set a bot's LHS icon image based on bot_user_id string parameter. Icon image must be SVG format, all other formats are rejected.

-
Permissions
-

Must have manage_bots permission. -Minimum server version: 5.14

-
Authorizations:
bearerAuth
path Parameters
bot_user_id
required
string

Bot user ID

-
Request Body schema: multipart/form-data
image
required
string <binary>

SVG icon image to be uploaded

-

Responses

200

SVG icon image set successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
413

Content too large

-
500

Something went wrong with the server

-
501

Feature is disabled

-
post /bots/{bot_user_id}/icon
http://your-mattermost-url.com/api/v4/bots/{bot_user_id}/icon
https://your-mattermost-url.com/api/v4/bots/{bot_user_id}/icon

Request samples

Copy
import (
-  "io/ioutil"
-  "log"
-
-  "github.com/mattermost/mattermost-server/model"
-)
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-data, err := ioutil.ReadFile("icon_image.svg")
-if err != nil {
-  log.Fatal(err)
-}
-
-botUserID := "4xp9fdt77pncbef59f4k1qe83o"
-
-ok, resp := Client.SetBotIconImage(botUserID, data)
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Delete bot's LHS icon image

Delete bot's LHS icon image based on bot_user_id string parameter.

-
Permissions
-

Must have manage_bots permission. -Minimum server version: 5.14

-
Authorizations:
bearerAuth
path Parameters
bot_user_id
required
string

Bot user ID

-

Responses

200

Icon image deletion successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
500

Something went wrong with the server

-
501

Feature is disabled

-
delete /bots/{bot_user_id}/icon
http://your-mattermost-url.com/api/v4/bots/{bot_user_id}/icon
https://your-mattermost-url.com/api/v4/bots/{bot_user_id}/icon

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-botUserID := "4xp9fdt77pncbef59f4k1qe83o"
-
-ok, resp := Client.DeleteBotIconImage(botUserID)
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

teams

Endpoints for creating, getting and interacting with teams.

-

Create a team

Create a new team on the system.

-
Permissions
-

Must be authenticated and have the create_team permission.

-
Authorizations:
bearerAuth
Request Body schema: application/json

Team that is to be created

-
name
required
string

Unique handler for a team, will be present in the team URL

-
display_name
required
string

Non-unique UI name for the team

-
type
required
string

'O' for open, 'I' for invite only

-

Responses

201

Team creation successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
post /teams
http://your-mattermost-url.com/api/v4/teams
https://your-mattermost-url.com/api/v4/teams

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "name": "string",
  • "display_name": "string",
  • "type": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "display_name": "string",
  • "name": "string",
  • "description": "string",
  • "email": "string",
  • "type": "string",
  • "allowed_domains": "string",
  • "invite_id": "string",
  • "allow_open_invite": true
}

Get teams

For regular users only returns open teams. Users with the "manage_system" permission will return teams regardless of type. The result is based on query string parameters - page and per_page.

-
Permissions
-

Must be authenticated. "manage_system" permission is required to show all teams.

-
Authorizations:
bearerAuth
query Parameters
page
integer
Default: 0

The page to select.

-
per_page
integer
Default: 60

The number of teams per page.

-
include_total_count
boolean
Default: false

Responses

200

Team list retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
get /teams
http://your-mattermost-url.com/api/v4/teams
https://your-mattermost-url.com/api/v4/teams

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-teams, resp := Client.GetAllTeams("", 0, 100)
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Get a team

Get a team on the system.

-
Permissions
-

Must be authenticated and have the view_team permission.

-
Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

-

Responses

200

Team retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
get /teams/{team_id}
http://your-mattermost-url.com/api/v4/teams/{team_id}
https://your-mattermost-url.com/api/v4/teams/{team_id}

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-teamID := "4xp9fdt77pncbef59f4k1qe83o"
-
-t, err := Client.GetTeam(teamID, "")
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "display_name": "string",
  • "name": "string",
  • "description": "string",
  • "email": "string",
  • "type": "string",
  • "allowed_domains": "string",
  • "invite_id": "string",
  • "allow_open_invite": true
}

Update a team

Update a team by providing the team object. The fields that can be updated are defined in the request body, all other provided fields will be ignored.

-
Permissions
-

Must have the manage_team permission.

-
Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

-
Request Body schema: application/json

Team to update

-
id
required
string
display_name
required
string
description
required
string
company_name
required
string
allowed_domains
required
string
invite_id
required
string
allow_open_invite
required
string

Responses

200

Team update successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
put /teams/{team_id}
http://your-mattermost-url.com/api/v4/teams/{team_id}
https://your-mattermost-url.com/api/v4/teams/{team_id}

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "display_name": "string",
  • "description": "string",
  • "company_name": "string",
  • "allowed_domains": "string",
  • "invite_id": "string",
  • "allow_open_invite": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "display_name": "string",
  • "name": "string",
  • "description": "string",
  • "email": "string",
  • "type": "string",
  • "allowed_domains": "string",
  • "invite_id": "string",
  • "allow_open_invite": true
}

Delete a team

Soft deletes a team, by marking the team as deleted in the database. Soft deleted teams will not be accessible in the user interface.

-

Optionally use the permanent query parameter to hard delete the team for compliance reasons. As of server version 5.0, to use this feature ServiceSettings.EnableAPITeamDeletion must be set to true in the server's configuration.

-
Permissions
-

Must have the manage_team permission.

-
Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

-
query Parameters
permanent
boolean
Default: false

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.

-

Responses

200

Team deletion successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
delete /teams/{team_id}
http://your-mattermost-url.com/api/v4/teams/{team_id}
https://your-mattermost-url.com/api/v4/teams/{team_id}

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-teamID := "4xp9fdt77pncbef59f4k1qe83o"
-
-// Non-permanent deletion
-ok, resp := Client.SoftDeleteTeam(&model.Team{Id: teamID})
-
-// Permanent deletion
-ok, resp := Client.PermanentDeleteTeam(&model.Team{Id: teamID})
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Patch a team

Partially update a team by providing only the fields you want to update. Omitted fields will not be updated. The fields that can be updated are defined in the request body, all other provided fields will be ignored.

-
Permissions
-

Must have the manage_team permission.

-
Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

-
Request Body schema: application/json

Team object that is to be updated

-
display_name
string
description
string
company_name
string
invite_id
string
allow_open_invite
boolean

Responses

200

team patch successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
put /teams/{team_id}/patch
http://your-mattermost-url.com/api/v4/teams/{team_id}/patch
https://your-mattermost-url.com/api/v4/teams/{team_id}/patch

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "display_name": "string",
  • "description": "string",
  • "company_name": "string",
  • "invite_id": "string",
  • "allow_open_invite": true
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "display_name": "string",
  • "name": "string",
  • "description": "string",
  • "email": "string",
  • "type": "string",
  • "allowed_domains": "string",
  • "invite_id": "string",
  • "allow_open_invite": true
}

Get a team by name

Get a team based on provided name string

-
Permissions
-

Must be authenticated, team type is open and have the view_team permission.

-
Authorizations:
bearerAuth
path Parameters
name
required
string

Team Name

-

Responses

200

Team retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
get /teams/name/{name}
http://your-mattermost-url.com/api/v4/teams/name/{name}
https://your-mattermost-url.com/api/v4/teams/name/{name}

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-team, resp := Client.GetTeamByName("teamName", "")
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "display_name": "string",
  • "name": "string",
  • "description": "string",
  • "email": "string",
  • "type": "string",
  • "allowed_domains": "string",
  • "invite_id": "string",
  • "allow_open_invite": true
}

Search teams

Search teams based on search term provided in the request body.

-
Permissions
-

Logged in user only shows open teams -Logged in user with "manage_system" permission shows all teams

-
Authorizations:
bearerAuth
Request Body schema: application/json

Search criteria

-
term
required
string

The search term to match against the name or display name of teams

-
page
string

The page number to return, if paginated. If this parameter is not present with the per_page parameter then the results will be returned un-paged.

-
per_page
string

The number of entries to return per page, if paginated. If this parameter is not present with the page parameter then the results will be returned un-paged.

-

Responses

200

Paginated teams response. (Note that the non-paginated response—returned if the request body does not contain both page and per_page fields—is a simple array of teams.)

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
post /teams/search
http://your-mattermost-url.com/api/v4/teams/search
https://your-mattermost-url.com/api/v4/teams/search

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "term": "string",
  • "page": "string",
  • "per_page": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "teams":
    [
    ],
  • "total_count": 0
}

Check if team exists

Check if the team exists based on a team name.

-
Permissions
-

Must be authenticated.

-
Authorizations:
bearerAuth
path Parameters
name
required
string

Team Name

-

Responses

200

Team retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
404

Resource not found

-
get /teams/name/{name}/exists
http://your-mattermost-url.com/api/v4/teams/name/{name}/exists
https://your-mattermost-url.com/api/v4/teams/name/{name}/exists

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-exists, resp := Client.TeamExists("teamName", "")
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "exists": true
}

Get a user's teams

Get a list of teams that a user is on.

-
Permissions
-

Must be authenticated as the user or have the manage_system permission.

-
Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

-

Responses

200

Team list retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
get /users/{user_id}/teams
http://your-mattermost-url.com/api/v4/users/{user_id}/teams
https://your-mattermost-url.com/api/v4/users/{user_id}/teams

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-userID := "4xp9fdt77pncbef59f4k1qe83o"
-
-teams, resp := Client.GetTeamsForUser(userID, "")
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Get team members

Get a page team members list based on query string parameters - team id, page and per page.

-
Permissions
-

Must be authenticated and have the view_team permission.

-
Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

-
query Parameters
page
integer
Default: 0

The page to select.

-
per_page
integer
Default: 60

The number of users per page.

-

Responses

200

Team members retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
get /teams/{team_id}/members
http://your-mattermost-url.com/api/v4/teams/{team_id}/members
https://your-mattermost-url.com/api/v4/teams/{team_id}/members

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-teamID := "4xp9fdt77pncbef59f4k1qe83o"
-
-members, resp := Client.GetTeamMembers(teamID, 0, 100, "")
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Add user to team

Add user to the team by user_id.

-
Permissions
-

Must be authenticated and team be open to add self. For adding another user, authenticated user must have the add_user_to_team permission.

-
Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

-
Request Body schema: application/json
team_id
string
user_id
string

Responses

201

Team member creation successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
post /teams/{team_id}/members
http://your-mattermost-url.com/api/v4/teams/{team_id}/members
https://your-mattermost-url.com/api/v4/teams/{team_id}/members

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "team_id": "string",
  • "user_id": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "team_id": "string",
  • "user_id": "string",
  • "roles": "string",
  • "delete_at": 0,
  • "scheme_user": true,
  • "scheme_admin": true,
  • "explicit_roles": "string"
}

Add user to team from invite

Using either an invite id or hash/data pair from an email invite link, add a user to a team.

-
Permissions
-

Must be authenticated.

-
Authorizations:
bearerAuth
query Parameters
token
required
string

Token id from the invitation

-

Responses

201

Team member creation successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
post /teams/members/invite
http://your-mattermost-url.com/api/v4/teams/members/invite
https://your-mattermost-url.com/api/v4/teams/members/invite

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-tokenID := "qjda3stwafbgpqjaxej3k76sga"
-
-tm, resp = Client.AddTeamMemberFromInvite(tokenID, "")
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "team_id": "string",
  • "user_id": "string",
  • "roles": "string",
  • "delete_at": 0,
  • "scheme_user": true,
  • "scheme_admin": true,
  • "explicit_roles": "string"
}

Add multiple users to team

Add a number of users to the team by user_id.

-
Permissions
-

Must be authenticated. Authenticated user must have the add_user_to_team permission.

-
Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

-
query Parameters
graceful
boolean

Instead of aborting the operation if a user cannot be added, return an arrray that will contain both the success and added members and the ones with error, in form of [{"member": {...}, "user_id", "...", "error": {...}}]

-
Request Body schema: application/json
Array
team_id
string

The ID of the team this member belongs to.

-
user_id
string

The ID of the user this member relates to.

-
roles
string

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.

-
delete_at
integer

The time in milliseconds that this team member was deleted.

-
scheme_user
boolean

Whether this team member holds the default user role defined by the team's permissions scheme.

-
scheme_admin
boolean

Whether this team member holds the default admin role defined by the team's permissions scheme.

-
explicit_roles
string

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.

-

Responses

201

Team members created successfully.

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
post /teams/{team_id}/members/batch
http://your-mattermost-url.com/api/v4/teams/{team_id}/members/batch
https://your-mattermost-url.com/api/v4/teams/{team_id}/members/batch

Request samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Get team members for a user

Get a list of team members for a user. Useful for getting the ids of teams the user is on and the roles they have in those teams.

-
Permissions
-

Must be logged in as the user or have the edit_other_users permission.

-
Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

-

Responses

200

Team members retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
get /users/{user_id}/teams/members
http://your-mattermost-url.com/api/v4/users/{user_id}/teams/members
https://your-mattermost-url.com/api/v4/users/{user_id}/teams/members

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-userID := "zWEyrTZ7GZ22aBSfoX60iWryTY"
-
-teamMembers, resp = Client.GetTeamMembersForUser(userID, "")
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Get a team member

Get a team member on the system.

-
Permissions
-

Must be authenticated and have the view_team permission.

-
Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

-
user_id
required
string

User GUID

-

Responses

200

Team member retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
get /teams/{team_id}/members/{user_id}
http://your-mattermost-url.com/api/v4/teams/{team_id}/members/{user_id}
https://your-mattermost-url.com/api/v4/teams/{team_id}/members/{user_id}

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-teamID := "zWEyrTZ7GZ22aBSfoX60iWryTY"
-userID := "NqCSr5HMDZjrWS74IEmedvlOYf"
-
-teamMember, resp = Client.GetTeamMember(teamID, userID, "")
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "team_id": "string",
  • "user_id": "string",
  • "roles": "string",
  • "delete_at": 0,
  • "scheme_user": true,
  • "scheme_admin": true,
  • "explicit_roles": "string"
}

Remove user from team

Delete the team member object for a user, effectively removing them from a team.

-
Permissions
-

Must be logged in as the user or have the remove_user_from_team permission.

-
Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

-
user_id
required
string

User GUID

-

Responses

200

Team member deletion successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
delete /teams/{team_id}/members/{user_id}
http://your-mattermost-url.com/api/v4/teams/{team_id}/members/{user_id}
https://your-mattermost-url.com/api/v4/teams/{team_id}/members/{user_id}

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-teamID := "zWEyrTZ7GZ22aBSfoX60iWryTY"
-userID := "NqCSr5HMDZjrWS74IEmedvlOYf"
-
-ok, resp = Client.RemoveTeamMember(teamID, userID)
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Get team members by ids

Get a list of team members based on a provided array of user ids.

-
Permissions
-

Must have view_team permission for the team.

-
Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

-
Request Body schema: application/json

List of user ids

-
Array
string

Responses

200

Team members retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
post /teams/{team_id}/members/ids
http://your-mattermost-url.com/api/v4/teams/{team_id}/members/ids
https://your-mattermost-url.com/api/v4/teams/{team_id}/members/ids

Request samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • "string"
]

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Get a team stats

Get a team stats on the system.

-
Permissions
-

Must be authenticated and have the view_team permission.

-
Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

-

Responses

200

Team stats retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
get /teams/{team_id}/stats
http://your-mattermost-url.com/api/v4/teams/{team_id}/stats
https://your-mattermost-url.com/api/v4/teams/{team_id}/stats

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-teamID := "zWEyrTZ7GZ22aBSfoX60iWryTY"
-
-stats, resp := Client.GetTeamStats(teamID, "")
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "team_id": "string",
  • "total_member_count": 0,
  • "active_member_count": 0
}

Regenerate the Invite ID from a Team

Regenerates the invite ID used in invite links of a team

-
Permissions
-

Must be authenticated and have the manage_team permission.

-
Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

-

Responses

200

Team Invite ID regenerated

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
post /teams/{team_id}/regenerate_invite_id
http://your-mattermost-url.com/api/v4/teams/{team_id}/regenerate_invite_id
https://your-mattermost-url.com/api/v4/teams/{team_id}/regenerate_invite_id

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-teamID := "zWEyrTZ7GZ22aBSfoX60iWryTY"
-
-team, resp := Client.RegenerateTeamInviteId(teamID)
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "display_name": "string",
  • "name": "string",
  • "description": "string",
  • "email": "string",
  • "type": "string",
  • "allowed_domains": "string",
  • "invite_id": "string",
  • "allow_open_invite": true
}

Get the team icon

Get the team icon of the team.

-

Minimum server version: 4.9

-
Permissions
-

User must be authenticated. In addition, team must be open or the user must have the view_team permission.

-
Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

-

Responses

200

Team icon retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
501

Feature is disabled

-
get /teams/{team_id}/image
http://your-mattermost-url.com/api/v4/teams/{team_id}/image
https://your-mattermost-url.com/api/v4/teams/{team_id}/image

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-teamID := "zWEyrTZ7GZ22aBSfoX60iWryTY"
-
-icon, resp = Client.GetTeamIcon(teamID, "")
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

Sets the team icon

Sets the team icon for the team.

-

Minimum server version: 4.9

-
Permissions
-

Must be authenticated and have the manage_team permission.

-
Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

-
Request Body schema: multipart/form-data
image
required
string <binary>

The image to be uploaded

-

Responses

200

Team icon successfully set

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
500

Something went wrong with the server

-
501

Feature is disabled

-
post /teams/{team_id}/image
http://your-mattermost-url.com/api/v4/teams/{team_id}/image
https://your-mattermost-url.com/api/v4/teams/{team_id}/image

Request samples

Copy
import (
-  "io/ioutil"
-  "log"
-
-  "github.com/mattermost/mattermost-server/model"
-)
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-data, err := ioutil.ReadFile("icon.png")
-if err != nil {
-  log.Fatal(err)
-}
-
-teamID := "zWEyrTZ7GZ22aBSfoX60iWryTY"
-
-ok, resp := Client.SetTeamIcon(teamID, data)
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Remove the team icon

Remove the team icon for the team.

-

Minimum server version: 4.10

-
Permissions
-

Must be authenticated and have the manage_team permission.

-
Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

-

Responses

200

Team icon successfully remove

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
500

Something went wrong with the server

-
501

Feature is disabled

-
delete /teams/{team_id}/image
http://your-mattermost-url.com/api/v4/teams/{team_id}/image
https://your-mattermost-url.com/api/v4/teams/{team_id}/image

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-teamID := "zWEyrTZ7GZ22aBSfoX60iWryTY"
-
-ok, resp = Client.RemoveTeamIcon(teamID)
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Update a team member roles

Update a team member roles. Valid team roles are "team_user", "team_admin" or both of them. Overwrites any previously assigned team roles.

-
Permissions
-

Must be authenticated and have the manage_team_roles permission.

-
Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

-
user_id
required
string

User GUID

-
Request Body schema: application/json

Space-delimited team roles to assign to the user

-
roles
required
string

Responses

200

Team member roles update successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
put /teams/{team_id}/members/{user_id}/roles
http://your-mattermost-url.com/api/v4/teams/{team_id}/members/{user_id}/roles
https://your-mattermost-url.com/api/v4/teams/{team_id}/members/{user_id}/roles

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "roles": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Update the scheme-derived roles of a team member.

Update a team member's scheme_admin/scheme_user properties. Typically this should either be scheme_admin=false, scheme_user=true for ordinary team member, or scheme_admin=true, scheme_user=true for a team admin.

-

Minimum server version: 5.0

-
Permissions
-

Must be authenticated and have the manage_team_roles permission.

-
Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

-
user_id
required
string

User GUID

-
Request Body schema: application/json

Scheme properties.

-
scheme_admin
required
boolean
scheme_user
required
boolean

Responses

200

Team member's scheme-derived roles updated successfully.

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
put /teams/{team_id}/members/{user_id}/schemeRoles
http://your-mattermost-url.com/api/v4/teams/{team_id}/members/{user_id}/schemeRoles
https://your-mattermost-url.com/api/v4/teams/{team_id}/members/{user_id}/schemeRoles

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "scheme_admin": true,
  • "scheme_user": true
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Get team unreads for a user

Get the count for unread messages and mentions in the teams the user is a member of.

-
Permissions
-

Must be logged in.

-
Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

-
query Parameters
exclude_team
required
string

Optional team id to be excluded from the results

-

Responses

200

Team unreads retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
get /users/{user_id}/teams/unread
http://your-mattermost-url.com/api/v4/users/{user_id}/teams/unread
https://your-mattermost-url.com/api/v4/users/{user_id}/teams/unread

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-userID := "NqCSr5HMDZjrWS74IEmedvlOYf"
-teamID := "zWEyrTZ7GZ22aBSfoX60iWryTY"
-
-teams, resp := Client.GetTeamsUnreadForUser(userID, teamID)
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Get unreads for a team

Get the unread mention and message counts for a team for the specified user.

-
Permissions
-

Must be the user or have edit_other_users permission and have view_team permission for the team.

-
Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

-
team_id
required
string

Team GUID

-

Responses

200

Team unread count retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
get /users/{user_id}/teams/{team_id}/unread
http://your-mattermost-url.com/api/v4/users/{user_id}/teams/{team_id}/unread
https://your-mattermost-url.com/api/v4/users/{user_id}/teams/{team_id}/unread

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-userID := "NqCSr5HMDZjrWS74IEmedvlOYf"
-teamID := "zWEyrTZ7GZ22aBSfoX60iWryTY"
-
-teamUnread, resp := Client.GetTeamUnread(userID, teamID)
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "team_id": "string",
  • "msg_count": 0,
  • "mention_count": 0
}

Invite users to the team by email

Invite users to the existing team usign the user's email.

-
Permissions
-

Must have invite_to_team permission for the team.

-
Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

-
Request Body schema: application/json

List of user's email

-
Array
string

Responses

200

Users invite successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
post /teams/{team_id}/invite/email
http://your-mattermost-url.com/api/v4/teams/{team_id}/invite/email
https://your-mattermost-url.com/api/v4/teams/{team_id}/invite/email

Request samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • "string"
]

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Invite guests to the team by email

Invite guests to existing team channels usign the user's email.

-

Minimum server version: 5.16

-
Permissions
-

Must have invite_guest permission for the team.

-
Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

-
Request Body schema: application/json

Guests invite information

-
emails
required
Array of strings

List of emails

-
channels
required
Array of strings

List of channel ids

-
message
string

Message to include in the invite

-

Responses

200

Guests invite successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
post /teams/{team_id}/invite-guests/email
http://your-mattermost-url.com/api/v4/teams/{team_id}/invite-guests/email
https://your-mattermost-url.com/api/v4/teams/{team_id}/invite-guests/email

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "emails":
    [
    ],
  • "channels":
    [
    ],
  • "message": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Invalidate active email invitations

Invalidate active email invitations that have not been accepted by the user.

-
Permissions
-

Must have manage_system permission.

-
Authorizations:
bearerAuth

Responses

200

Email invites successfully revoked

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
delete /teams/invites/email
http://your-mattermost-url.com/api/v4/teams/invites/email
https://your-mattermost-url.com/api/v4/teams/invites/email

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-ok, resp := Client.InvalidateEmailInvites()
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Import a Team from other application

Import a team into a existing team. Import users, channels, posts, hooks.

-
Permissions
-

Must have permission_import_team permission.

-
Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

-
Request Body schema: multipart/form-data
file
required
string <binary>

A file to be uploaded in zip format.

-
filesize
required
integer

The size of the zip file to be imported.

-
importFrom
required
string

String that defines from which application the team was exported to be imported into Mattermost.

-

Responses

200

JSON object containing a base64 encoded text file of the import logs in its results property.

-
400

Invalid or missing parameters in URL or request body

-
403

Do not have appropriate permissions

-
post /teams/{team_id}/import
http://your-mattermost-url.com/api/v4/teams/{team_id}/import
https://your-mattermost-url.com/api/v4/teams/{team_id}/import

Request samples

Copy
import (
-  "encoding/binary"
-  "io/ioutil"
-  "log"
-
-  "github.com/mattermost/mattermost-server/model"
-)
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-data, err = ioutil.ReadFile("to_import.zip")
-if err != nil && len(data) == 0 {
-  log.Fatal("Error while reading file.")
-}
-
-teamID := "zWEyrTZ7GZ22aBSfoX60iWryTY"
-
-fileResp, resp := Client.ImportTeam(data, binary.Size(data), "slack", "to_import.zip", teamID)
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "results": "string"
}

Get invite info for a team

Get the name, display_name, description and id for a team from the invite id.

-

Minimum server version: 4.0

-
Permissions
-

No authentication required.

-
Authorizations:
bearerAuth
path Parameters
invite_id
required
string

Invite id for a team

-

Responses

200

Team invite info retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
get /teams/invite/{invite_id}
http://your-mattermost-url.com/api/v4/teams/invite/{invite_id}
https://your-mattermost-url.com/api/v4/teams/invite/{invite_id}

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-
-inviteID := "zWEyrTZ7GZ22aBSfoX60iWryTY"
-
-team, resp = Client.GetTeamInviteInfo(inviteID)
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "name": "string",
  • "display_name": "string",
  • "description": "string"
}

Set a team's scheme

Set a team's scheme, more specifically sets the scheme_id value of a team record.

-
Permissions
-

Must have manage_system permission.

-

Minimum server version: 5.0

-
Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

-
Request Body schema: application/json

Scheme GUID

-
scheme_id
required
string

The ID of the scheme.

-

Responses

200

Update team scheme successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
501

Feature is disabled

-
put /teams/{team_id}/scheme
http://your-mattermost-url.com/api/v4/teams/{team_id}/scheme
https://your-mattermost-url.com/api/v4/teams/{team_id}/scheme

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "scheme_id": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Team members minus group members.

Get the set of users who are members of the team minus the set of users who are members of the given groups. -Each user object contains an array of group objects representing the group memberships for that user. -Each user object contains the boolean fields scheme_guest, scheme_user, and scheme_admin representing the roles that user has for the given team.

-
Permissions
-

Must have manage_system permission.

-

Minimum server version: 5.14

-
Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

-
query Parameters
group_ids
required
string
Default: ""

A comma-separated list of group ids.

-
page
integer
Default: 0

The page to select.

-
per_page
integer
Default: 0

The number of users per page.

-

Responses

200

Successfully returns users specified by the pagination, and the total_count.

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
get /teams/{team_id}/members_minus_group_members
http://your-mattermost-url.com/api/v4/teams/{team_id}/members_minus_group_members
https://your-mattermost-url.com/api/v4/teams/{team_id}/members_minus_group_members

Request samples

Copy
curl 'http://your-mattermost-url.com/api/v4/teams/fcnst115y3y7xmzzp5uq34u8ce/members_minus_group_members?group_ids=eoezijg8zffgjmch8icy5bjd1e,ugaw6wjc3tfxpcr1eq5u5k8dhe&page=0&per_page=100' \
-    -H 'Authorization: Bearer mq8rrfxpdfyafbnw3qfmhwkx6c' \
-    -H 'Content-Type: application/json' \
-    -H 'X-Requested-With: XMLHttpRequest'
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

channels

Endpoints for creating, getting and interacting with channels.

-

Create a channel

Create a new channel.

-
Permissions
-

If creating a public channel, create_public_channel permission is required. If creating a private channel, create_private_channel permission is required.

-
Authorizations:
bearerAuth
Request Body schema: application/json

Channel object to be created

-
team_id
required
string

The team ID of the team to create the channel on

-
name
required
string

The unique handle for the channel, will be present in the channel URL

-
display_name
required
string

The non-unique UI name for the channel

-
purpose
string

A short description of the purpose of the channel

-
header
string

Markdown-formatted text to display in the header of the channel

-
type
required
string

'O' for a public channel, 'P' for a private channel

-

Responses

201

Channel creation successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
post /channels
http://your-mattermost-url.com/api/v4/channels
https://your-mattermost-url.com/api/v4/channels

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "team_id": "string",
  • "name": "string",
  • "display_name": "string",
  • "purpose": "string",
  • "header": "string",
  • "type": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

Create a direct message channel

Create a new direct message channel between two users.

-
Permissions
-

Must be one of the two users and have create_direct_channel permission. Having the manage_system permission voids the previous requirements.

-
Authorizations:
bearerAuth
Request Body schema: application/json

The two user ids to be in the direct message

-
Array
string

Responses

201

Direct channel creation successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
post /channels/direct
http://your-mattermost-url.com/api/v4/channels/direct
https://your-mattermost-url.com/api/v4/channels/direct

Request samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • "string",
  • "string"
]

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

Create a group message channel

Create a new group message channel to group of users. If the logged in user's id is not included in the list, it will be appended to the end.

-
Permissions
-

Must have create_group_channel permission.

-
Authorizations:
bearerAuth
Request Body schema: application/json

User ids to be in the group message channel

-
Array
string

Responses

201

Group channel creation successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
post /channels/group
http://your-mattermost-url.com/api/v4/channels/group
https://your-mattermost-url.com/api/v4/channels/group

Request samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • "string"
]

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

Search all private and open type channels across all teams

Returns all private and open type channels where 'term' matches on the name, display name, or purpose of -the channel.

-

Configured 'default' channels (ex Town Square and Off-Topic) can be excluded from the results -with the exclude_default_channels boolean parameter.

-

Channels that are associated (via GroupChannel records) to a given group can be excluded from the results -with the not_associated_to_group parameter and a group id string.

-
Authorizations:
bearerAuth
Request Body schema: application/json

The search terms and logic to use in the search.

-
term
required
string

The string to search in the channel name, display name, and purpose.

-
not_associated_to_group
string

A group id to exclude channels that are associated to that group via GroupChannel records.

-
exclude_default_channels
boolean

Exclude default channels from the results by setting this parameter to true.

-
page
string

The page number to return, if paginated. If this parameter is not present with the per_page parameter then the results will be returned un-paged.

-
per_page
string

The number of entries to return per page, if paginated. If this parameter is not present with the page parameter then the results will be returned un-paged.

-

Responses

200

Paginated channel response. (Note that the non-paginated response—returned if the request body does not contain both page and per_page fields—is a simple array of channels.)

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
post /channels/search
http://your-mattermost-url.com/api/v4/channels/search
https://your-mattermost-url.com/api/v4/channels/search

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "term": "string",
  • "not_associated_to_group": "string",
  • "exclude_default_channels": true,
  • "page": "string",
  • "per_page": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

Search Group Channels

Get a list of group channels for a user which members' usernames match the search term.

-

Minimum server version: 5.14

-
Authorizations:
bearerAuth
Request Body schema: application/json

Search criteria

-
term
required
string

The search term to match against the members' usernames of the group channels

-

Responses

200

Channels search successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
post /group/search
http://your-mattermost-url.com/api/v4/group/search
https://your-mattermost-url.com/api/v4/group/search

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "term": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

Get a list of channels by ids

Get a list of public channels on a team by id.

-
Permissions
-

view_team for the team the channels are on.

-
Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

-
Request Body schema: application/json

List of channel ids

-
Array
string

Responses

200

Channel list retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
404

Resource not found

-
post /teams/{team_id}/channels/ids
http://your-mattermost-url.com/api/v4/teams/{team_id}/channels/ids
https://your-mattermost-url.com/api/v4/teams/{team_id}/channels/ids

Request samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • "string"
]

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

Get timezones in a channel

Get a list of timezones for the users who are in this channel.

-

Minimum server version: 5.6

-
Permissions
-

Must have the read_channel permission.

-
Authorizations:
bearerAuth
path Parameters
channel_id
required
string

Channel GUID

-

Responses

200

Timezone retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
get /channels/{channel_id}/timezones
http://your-mattermost-url.com/api/v4/channels/{channel_id}/timezones
https://your-mattermost-url.com/api/v4/channels/{channel_id}/timezones

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-// GetChannelStats
-stats, resp := Client.GetChannelTimezones(<CHANNELID>)
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

Get a channel

Get channel from the provided channel id string.

-
Permissions
-

read_channel permission for the channel.

-
Authorizations:
bearerAuth
path Parameters
channel_id
required
string

Channel GUID

-

Responses

200

Channel retrieval successful

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
get /channels/{channel_id}
http://your-mattermost-url.com/api/v4/channels/{channel_id}
https://your-mattermost-url.com/api/v4/channels/{channel_id}

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-// GetChannel
-channel, resp := Client.GetChannel(<CHANNELID>, "")
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

Update a channel

Update a channel. The fields that can be updated are listed as parameters. Omitted fields will be treated as blanks.

-
Permissions
-

If updating a public channel, manage_public_channel_members permission is required. If updating a private channel, manage_private_channel_members permission is required.

-
Authorizations:
bearerAuth
path Parameters
channel_id
required
string

Channel GUID

-
Request Body schema: application/json

Channel object to be updated

-
id
required
string

The channel's id, not updatable

-
name
string

The unique handle for the channel, will be present in the channel URL

-
display_name
string

The non-unique UI name for the channel

-
purpose
string

A short description of the purpose of the channel

-
header
string

Markdown-formatted text to display in the header of the channel

-

Responses

200

Channel update successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
put /channels/{channel_id}
http://your-mattermost-url.com/api/v4/channels/{channel_id}
https://your-mattermost-url.com/api/v4/channels/{channel_id}

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "name": "string",
  • "display_name": "string",
  • "purpose": "string",
  • "header": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

Delete a channel

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.

-
Permissions
-

delete_public_channel permission if the channel is public, -delete_private_channel permission if the channel is private, -or have manage_system permission.

-
Authorizations:
bearerAuth
path Parameters
channel_id
required
string

Channel GUID

-

Responses

200

Channel deletion successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
delete /channels/{channel_id}
http://your-mattermost-url.com/api/v4/channels/{channel_id}
https://your-mattermost-url.com/api/v4/channels/{channel_id}

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-// DeleteChannel
-pass, resp := Client.DeleteChannel(<CHANNELID>)
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

Patch a channel

Partially update a channel by providing only the fields you want to update. Omitted fields will not be updated. The fields that can be updated are defined in the request body, all other provided fields will be ignored.

-
Permissions
-

If updating a public channel, manage_public_channel_members permission is required. If updating a private channel, manage_private_channel_members permission is required.

-
Authorizations:
bearerAuth
path Parameters
channel_id
required
string

Channel GUID

-
Request Body schema: application/json

Channel object to be updated

-
name
string

The unique handle for the channel, will be present in the channel URL

-
display_name
string

The non-unique UI name for the channel

-
purpose
string

A short description of the purpose of the channel

-
header
string

Markdown-formatted text to display in the header of the channel

-

Responses

200

Channel patch successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
put /channels/{channel_id}/patch
http://your-mattermost-url.com/api/v4/channels/{channel_id}/patch
https://your-mattermost-url.com/api/v4/channels/{channel_id}/patch

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "name": "string",
  • "display_name": "string",
  • "purpose": "string",
  • "header": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

Update channel's privacy

Updates channel's privacy allowing changing a channel from Public to Private and back.

-

Minimum server version: 5.16

-
Permissions
-

manage_team permission for the team of the channel.

-
Authorizations:
bearerAuth
path Parameters
channel_id
required
string

Channel GUID

-
Request Body schema: application/json
privacy
required
string

Channel privacy setting: 'O' for a public channel, 'P' for a private channel

-

Responses

200

Channel conversion successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
put /channels/{channel_id}/privacy
http://your-mattermost-url.com/api/v4/channels/{channel_id}/privacy
https://your-mattermost-url.com/api/v4/channels/{channel_id}/privacy

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "privacy": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

Convert a channel from public to private

Will be deprecated in 6.0

-

Convert into private channel from the provided channel id string.

-

Minimum server version: 4.10

-
Permissions
-

manage_team permission for the team of the channel.

-
Authorizations:
bearerAuth
path Parameters
channel_id
required
string

Channel GUID

-

Responses

200

Channel conversion successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
post /channels/{channel_id}/convert
http://your-mattermost-url.com/api/v4/channels/{channel_id}/convert
https://your-mattermost-url.com/api/v4/channels/{channel_id}/convert

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-// ConvertChannelToPrivate
-convertedChannel, resp := Client.ConvertChannelToPrivate(<CHANNELID>)
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

Restore a channel

Restore channel from the provided channel id string.

-

Minimum server version: 3.10

-
Permissions
-

manage_team permission for the team of the channel.

-
Authorizations:
bearerAuth
path Parameters
channel_id
required
string

Channel GUID

-

Responses

200

Channel restore successful

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
post /channels/{channel_id}/restore
http://your-mattermost-url.com/api/v4/channels/{channel_id}/restore
https://your-mattermost-url.com/api/v4/channels/{channel_id}/restore

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

Get channel statistics

Get statistics for a channel.

-
Permissions
-

Must have the read_channel permission.

-
Authorizations:
bearerAuth
path Parameters
channel_id
required
string

Channel GUID

-

Responses

200

Channel statistics retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
get /channels/{channel_id}/stats
http://your-mattermost-url.com/api/v4/channels/{channel_id}/stats
https://your-mattermost-url.com/api/v4/channels/{channel_id}/stats

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-// GetChannelStats
-stats, resp := Client.GetChannelStats(<CHANNELID>)
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

Get a channel's pinned posts

Get a list of pinned posts for channel.

-
Authorizations:
bearerAuth
path Parameters
channel_id
required
string

Channel GUID

-

Responses

200

The list of channel pinned posts

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
get /channels/{channel_id}/pinned
http://your-mattermost-url.com/api/v4/channels/{channel_id}/pinned
https://your-mattermost-url.com/api/v4/channels/{channel_id}/pinned

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-// GetPinnedPosts
-posts, resp := Client.GetPinnedPosts(<CHANNELID>, "")
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

Get public channels

Get a page of public channels on a team based on query string parameters - page and per_page.

-
Permissions
-

Must be authenticated and have the list_team_channels permission.

-
Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

-
query Parameters
page
integer
Default: 0

The page to select.

-
per_page
integer
Default: 60

The number of public channels per page.

-

Responses

200

Channels retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
get /teams/{team_id}/channels
http://your-mattermost-url.com/api/v4/teams/{team_id}/channels
https://your-mattermost-url.com/api/v4/teams/{team_id}/channels

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-// GetPublicChannelsForTeam
-channels, resp := Client.GetPublicChannelsForTeam(<TEAMID>, 0, 100, "")
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

Get deleted channels

Get a page of deleted channels on a team based on query string parameters - team_id, page and per_page.

-

Minimum server version: 3.10

-
Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

-
query Parameters
page
integer
Default: 0

The page to select.

-
per_page
integer
Default: 60

The number of public channels per page.

-

Responses

200

Channels retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
get /teams/{team_id}/channels/deleted
http://your-mattermost-url.com/api/v4/teams/{team_id}/channels/deleted
https://your-mattermost-url.com/api/v4/teams/{team_id}/channels/deleted

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

Autocomplete channels

Autocomplete public channels on a team based on the search term provided in the request URL.

-

Minimum server version: 4.7

-
Permissions
-

Must have the list_team_channels permission.

-
Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

-
query Parameters
name
required
string

Name or display name

-

Responses

200

Channels autocomplete successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
get /teams/{team_id}/channels/autocomplete
http://your-mattermost-url.com/api/v4/teams/{team_id}/channels/autocomplete
https://your-mattermost-url.com/api/v4/teams/{team_id}/channels/autocomplete

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

Autocomplete channels for search

Autocomplete your channels on a team based on the search term provided in the request URL.

-

Minimum server version: 5.4

-
Permissions
-

Must have the list_team_channels permission.

-
Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

-
query Parameters
name
required
string

Name or display name

-

Responses

200

Channels autocomplete successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
get /teams/{team_id}/channels/search_autocomplete
http://your-mattermost-url.com/api/v4/teams/{team_id}/channels/search_autocomplete
https://your-mattermost-url.com/api/v4/teams/{team_id}/channels/search_autocomplete

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

Search channels

Search public channels on a team based on the search term provided in the request body.

-
Permissions
-

Must have the list_team_channels permission.

-

In server version 5.16 and later, a user without the list_team_channels permission will be able to use this endpoint, with the search results limited to the channels that the user is a member of.

-
Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

-
Request Body schema: application/json

Search criteria

-
term
required
string

The search term to match against the name or display name of channels

-

Responses

201

Channels search successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
post /teams/{team_id}/channels/search
http://your-mattermost-url.com/api/v4/teams/{team_id}/channels/search
https://your-mattermost-url.com/api/v4/teams/{team_id}/channels/search

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "term": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

Search archived channels

Search archived channels on a team based on the search term provided in the request body.

-

Minimum server version: 5.18

-
Permissions
-

Must have the list_team_channels permission.

-

In server version 5.18 and later, a user without the list_team_channels permission will be able to use this endpoint, with the search results limited to the channels that the user is a member of.

-
Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

-
Request Body schema: application/json

Search criteria

-
term
required
string

The search term to match against the name or display name of archived channels

-

Responses

201

Channels search successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
post /teams/{team_id}/channels/search_archived
http://your-mattermost-url.com/api/v4/teams/{team_id}/channels/search_archived
https://your-mattermost-url.com/api/v4/teams/{team_id}/channels/search_archived

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "term": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

Get a channel by name

Gets channel from the provided team id and channel name strings.

-
Permissions
-

read_channel permission for the channel.

-
Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

-
channel_name
required
string

Channel Name

-
query Parameters
include_deleted
boolean
Default: false

Defines if deleted channels should be returned or not

-

Responses

200

Channel retrieval successful

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
get /teams/{team_id}/channels/name/{channel_name}
http://your-mattermost-url.com/api/v4/teams/{team_id}/channels/name/{channel_name}
https://your-mattermost-url.com/api/v4/teams/{team_id}/channels/name/{channel_name}

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-// GetChannelByName
-channel, resp := Client.GetChannelByName(<CHANNEL NAME>, <TEAMID>, "")
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

Get a channel by name and team name

Gets a channel from the provided team name and channel name strings.

-
Permissions
-

read_channel permission for the channel.

-
Authorizations:
bearerAuth
path Parameters
team_name
required
string

Team Name

-
channel_name
required
string

Channel Name

-
query Parameters
include_deleted
boolean
Default: false

Defines if deleted channels should be returned or not

-

Responses

200

Channel retrieval successful

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
get /teams/name/{team_name}/channels/name/{channel_name}
http://your-mattermost-url.com/api/v4/teams/name/{team_name}/channels/name/{channel_name}
https://your-mattermost-url.com/api/v4/teams/name/{team_name}/channels/name/{channel_name}

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-// GetChannelByNameForTeamName
-channel, resp = Client.GetChannelByNameForTeamName(<CHANNEL NAME>, <TEAM NAME>, "")
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

Get channel members

Get a page of members for a channel.

-
Permissions
-

read_channel permission for the channel.

-
Authorizations:
bearerAuth
path Parameters
channel_id
required
string

Channel GUID

-
query Parameters
page
integer
Default: 0

The page to select.

-
per_page
integer
Default: 60

The number of members per page.

-

Responses

200

Channel members retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
get /channels/{channel_id}/members
http://your-mattermost-url.com/api/v4/channels/{channel_id}/members
https://your-mattermost-url.com/api/v4/channels/{channel_id}/members

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-// GetChannelMembers
-members, resp := Client.GetChannelMembers(th.BasicChannel.Id, 0, 60, "")
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

Add user to channel

Add a user to a channel by creating a channel member object.

-
Authorizations:
bearerAuth
path Parameters
channel_id
required
string

The channel ID

-
Request Body schema: application/json
user_id
required
string

The ID of user to add into the channel

-
post_root_id
string

The ID of root post where link to add channel member originates

-

Responses

201

Channel member creation successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
post /channels/{channel_id}/members
http://your-mattermost-url.com/api/v4/channels/{channel_id}/members
https://your-mattermost-url.com/api/v4/channels/{channel_id}/members

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "user_id": "string",
  • "post_root_id": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

Get channel members by ids

Get a list of channel members based on the provided user ids.

-
Permissions
-

Must have the read_channel permission.

-
Authorizations:
bearerAuth
path Parameters
channel_id
required
string

Channel GUID

-
Request Body schema: application/json

List of user ids

-
Array
string

Responses

200

Channel member list retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
post /channels/{channel_id}/members/ids
http://your-mattermost-url.com/api/v4/channels/{channel_id}/members/ids
https://your-mattermost-url.com/api/v4/channels/{channel_id}/members/ids

Request samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • "string"
]

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

Get channel member

Get a channel member.

-
Permissions
-

read_channel permission for the channel.

-
Authorizations:
bearerAuth
path Parameters
channel_id
required
string

Channel GUID

-
user_id
required
string

User GUID

-

Responses

200

Channel member retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
get /channels/{channel_id}/members/{user_id}
http://your-mattermost-url.com/api/v4/channels/{channel_id}/members/{user_id}
https://your-mattermost-url.com/api/v4/channels/{channel_id}/members/{user_id}

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-// GetChannelMember
-member, resp := Client.GetChannelMember(<CHANNELID>, <USERID>, "")
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

Remove user from channel

Delete a channel member, effectively removing them from a channel.

-

In server version 5.3 and later, channel members can only be deleted from public or private channels.

-
Permissions
-

manage_public_channel_members permission if the channel is public. -manage_private_channel_members permission if the channel is private.

-
Authorizations:
bearerAuth
path Parameters
channel_id
required
string

Channel GUID

-
user_id
required
string

User GUID

-

Responses

200

Channel member deletion successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
delete /channels/{channel_id}/members/{user_id}
http://your-mattermost-url.com/api/v4/channels/{channel_id}/members/{user_id}
https://your-mattermost-url.com/api/v4/channels/{channel_id}/members/{user_id}

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-// RemoveUserFromChannel
-pass, resp := Client.RemoveUserFromChannel(<CHANNELID>, <USERID>)
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

Update channel roles

Update a user's roles for a channel.

-
Permissions
-

Must have manage_channel_roles permission for the channel.

-
Authorizations:
bearerAuth
path Parameters
channel_id
required
string

Channel GUID

-
user_id
required
string

User GUID

-
Request Body schema: application/json

Space-delimited channel roles to assign to the user

-
roles
required
string

Responses

200

Channel roles update successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
put /channels/{channel_id}/members/{user_id}/roles
http://your-mattermost-url.com/api/v4/channels/{channel_id}/members/{user_id}/roles
https://your-mattermost-url.com/api/v4/channels/{channel_id}/members/{user_id}/roles

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "roles": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

Update the scheme-derived roles of a channel member.

Update a channel member's scheme_admin/scheme_user properties. Typically this should either be scheme_admin=false, scheme_user=true for ordinary channel member, or scheme_admin=true, scheme_user=true for a channel admin. -Minimum server version: 5.0

-
Permissions
-

Must be authenticated and have the manage_channel_roles permission.

-
Authorizations:
bearerAuth
path Parameters
channel_id
required
string

Channel GUID

-
user_id
required
string

User GUID

-
Request Body schema: application/json

Scheme properties.

-
scheme_admin
required
boolean
scheme_user
required
boolean

Responses

200

Channel member's scheme-derived roles updated successfully.

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
put /channels/{channel_id}/members/{user_id}/schemeRoles
http://your-mattermost-url.com/api/v4/channels/{channel_id}/members/{user_id}/schemeRoles
https://your-mattermost-url.com/api/v4/channels/{channel_id}/members/{user_id}/schemeRoles

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "scheme_admin": true,
  • "scheme_user": true
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

Update channel notifications

Update a user's notification properties for a channel. Only the provided fields are updated.

-
Permissions
-

Must be logged in as the user or have edit_other_users permission.

-
Authorizations:
bearerAuth
path Parameters
channel_id
required
string

Channel GUID

-
user_id
required
string

User GUID

-
Request Body schema: application/json
email
boolean

Set to "true" to enable email notifications, "false" to disable, or "default" to use the global user notification setting.

-
push
string

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
string

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
string

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

Channel notification properties update successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
put /channels/{channel_id}/members/{user_id}/notify_props
http://your-mattermost-url.com/api/v4/channels/{channel_id}/members/{user_id}/notify_props
https://your-mattermost-url.com/api/v4/channels/{channel_id}/members/{user_id}/notify_props

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "email": true,
  • "push": "string",
  • "desktop": "string",
  • "mark_unread": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

View channel

Perform all the actions involved in viewing a channel. This includes marking channels as read, clearing push notifications, and updating the active channel.

-
Permissions
-

Must be logged in as user or have edit_other_users permission.

-

Response only includes last_viewed_at_times in Mattermost server 4.3 and newer.

-
Authorizations:
bearerAuth
path Parameters
user_id
required
string

User ID to perform the view action for

-
Request Body schema: application/json

Paremeters affecting how and which channels to view

-
channel_id
required
string

The channel ID that is being viewed. Use a blank string to indicate that all channels have lost focus.

-
prev_channel_id
string

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

Channel view successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
post /channels/members/{user_id}/view
http://your-mattermost-url.com/api/v4/channels/members/{user_id}/view
https://your-mattermost-url.com/api/v4/channels/members/{user_id}/view

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "channel_id": "string",
  • "prev_channel_id": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

Get channel memberships and roles for a user

Get all channel memberships and associated membership roles (i.e. channel_user, channel_admin) for a user on a specific team.

-
Permissions
-

Logged in as the user and view_team permission for the team. Having manage_system permission voids the previous requirements.

-
Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

-
team_id
required
string

Team GUID

-

Responses

200

Channel members retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
get /users/{user_id}/teams/{team_id}/channels/members
http://your-mattermost-url.com/api/v4/users/{user_id}/teams/{team_id}/channels/members
https://your-mattermost-url.com/api/v4/users/{user_id}/teams/{team_id}/channels/members

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-// GetChannelMembersForUser
-members, resp := Client.GetChannelMembersForUser(<USERID>, <TEAMID>, "")
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

Get channels for user

Get all the channels on a team for a user.

-
Permissions
-

Logged in as the user, or have edit_other_users permission, and view_team permission for the team.

-
Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

-
team_id
required
string

Team GUID

-

Responses

200

Channels retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
get /users/{user_id}/teams/{team_id}/channels
http://your-mattermost-url.com/api/v4/users/{user_id}/teams/{team_id}/channels
https://your-mattermost-url.com/api/v4/users/{user_id}/teams/{team_id}/channels

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-// GetChannelsForTeamForUser
-channels, resp := Client.GetChannelsForTeamForUser(<TEAMID>, <USERID>, "")
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

Get unread messages

Get the total unread messages and mentions for a channel for a user.

-
Permissions
-

Must be logged in as user and have the read_channel permission, or have edit_other_usrs permission.

-
Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

-
channel_id
required
string

Channel GUID

-

Responses

200

Channel unreads retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
get /users/{user_id}/channels/{channel_id}/unread
http://your-mattermost-url.com/api/v4/users/{user_id}/channels/{channel_id}/unread
https://your-mattermost-url.com/api/v4/users/{user_id}/channels/{channel_id}/unread

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-// GetChannelUnread
-channelUnread, resp := Client.GetChannelUnread(<CHANNELID>, <USERID>)
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

Set a channel's scheme

Set a channel's scheme, more specifically sets the scheme_id value of a channel record.

-
Permissions
-

Must have manage_system permission.

-

Minimum server version: 4.10

-
Authorizations:
bearerAuth
path Parameters
channel_id
required
string

Channel GUID

-
Request Body schema: application/json

Scheme GUID

-
scheme_id
required
string

The ID of the scheme.

-

Responses

200

Update channel scheme successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
501

Feature is disabled

-
put /channels/{channel_id}/scheme
http://your-mattermost-url.com/api/v4/channels/{channel_id}/scheme
https://your-mattermost-url.com/api/v4/channels/{channel_id}/scheme

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "scheme_id": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

Channel members minus group members.

Get the set of users who are members of the channel minus the set of users who are members of the given groups. -Each user object contains an array of group objects representing the group memberships for that user. -Each user object contains the boolean fields scheme_guest, scheme_user, and scheme_admin representing the roles that user has for the given channel.

-
Permissions
-

Must have manage_system permission.

-

Minimum server version: 5.14

-
Authorizations:
bearerAuth
path Parameters
channel_id
required
string

Channel GUID

-
query Parameters
group_ids
required
string
Default: ""

A comma-separated list of group ids.

-
page
integer
Default: 0

The page to select.

-
per_page
integer
Default: 0

The number of users per page.

-

Responses

200

Successfully returns users specified by the pagination, and the total_count.

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
get /channels/{channel_id}/members_minus_group_members
http://your-mattermost-url.com/api/v4/channels/{channel_id}/members_minus_group_members
https://your-mattermost-url.com/api/v4/channels/{channel_id}/members_minus_group_members

Request samples

Copy
curl -X GET \
-  'http://your-mattermost-url.com/api/v4/channels/3wyp678obid8pggjmhmhwpah1r/members_minus_group_members?group_ids=eoezijg8zffgjmch8icy5bjd1e,ugaw6wjc3tfxpcr1eq5u5k8dhe&page=0&per_page=100' \
-  -H 'Authorization: Bearer kno8tcdotpbx3dj1gzcbx9jrqy' \
-  -H 'Content-Type: application/json' \
-  -H 'X-Requested-With: XMLHttpRequest'
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

posts

Endpoints for creating, getting and interacting with posts.

-

Create a post

Create a new post in a channel. To create the post as a comment on another post, provide root_id.

-
Permissions
-

Must have create_post permission for the channel the post is being created in.

-
Authorizations:
bearerAuth
query Parameters
set_online
boolean

Whether to set the user status as online or not.

-
Request Body schema: application/json

Post object to create

-
channel_id
required
string

The channel ID to post in

-
message
required
string

The message contents, can be formatted with Markdown

-
root_id
string

The post ID to comment on

-
file_ids
Array of strings

A list of file IDs to associate with the post. Note that posts are limited to 5 files maximum. Please use additional posts for more files.

-
props
object

A general JSON property bag to attach to the post

-

Responses

201

Post creation successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
post /posts
http://your-mattermost-url.com/api/v4/posts
https://your-mattermost-url.com/api/v4/posts

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "channel_id": "string",
  • "message": "string",
  • "root_id": "string",
  • "file_ids":
    [
    ],
  • "props": { }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "edit_at": 0,
  • "user_id": "string",
  • "channel_id": "string",
  • "root_id": "string",
  • "parent_id": "string",
  • "original_id": "string",
  • "message": "string",
  • "type": "string",
  • "props": { },
  • "hashtag": "string",
  • "filenames":
    [
    ],
  • "file_ids":
    [
    ],
  • "pending_post_id": "string",
  • "metadata":
    {
    }
}

Create a ephemeral post

Create a new ephemeral post in a channel.

-
Permissions
-

Must have create_post_ephemeral permission (currently only given to system admin)

-
Authorizations:
bearerAuth
Request Body schema: application/json

Ephemeral Post object to send

-
user_id
required
string

The target user id for the ephemeral post

-
post
required
object

Post object to create

-

Responses

201

Post creation successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
post /posts/ephemeral
http://your-mattermost-url.com/api/v4/posts/ephemeral
https://your-mattermost-url.com/api/v4/posts/ephemeral

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "user_id": "string",
  • "post":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "edit_at": 0,
  • "user_id": "string",
  • "channel_id": "string",
  • "root_id": "string",
  • "parent_id": "string",
  • "original_id": "string",
  • "message": "string",
  • "type": "string",
  • "props": { },
  • "hashtag": "string",
  • "filenames":
    [
    ],
  • "file_ids":
    [
    ],
  • "pending_post_id": "string",
  • "metadata":
    {
    }
}

Get a post

Get a single post.

-
Permissions
-

Must have read_channel permission for the channel the post is in or if the channel is public, have the read_public_channels permission for the team.

-
Authorizations:
bearerAuth
path Parameters
post_id
required
string

ID of the post to get

-

Responses

200

Post retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
get /posts/{post_id}
http://your-mattermost-url.com/api/v4/posts/{post_id}
https://your-mattermost-url.com/api/v4/posts/{post_id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "edit_at": 0,
  • "user_id": "string",
  • "channel_id": "string",
  • "root_id": "string",
  • "parent_id": "string",
  • "original_id": "string",
  • "message": "string",
  • "type": "string",
  • "props": { },
  • "hashtag": "string",
  • "filenames":
    [
    ],
  • "file_ids":
    [
    ],
  • "pending_post_id": "string",
  • "metadata":
    {
    }
}

Delete a post

Soft deletes a post, by marking the post as deleted in the database. Soft deleted posts will not be returned in post queries.

-
Permissions
-

Must be logged in as the user or have delete_others_posts permission.

-
Authorizations:
bearerAuth
path Parameters
post_id
required
string

ID of the post to delete

-

Responses

200

Post deletion successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
delete /posts/{post_id}
http://your-mattermost-url.com/api/v4/posts/{post_id}
https://your-mattermost-url.com/api/v4/posts/{post_id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Update a post

Update a post. Only the fields listed below are updatable, omitted fields will be treated as blank.

-
Permissions
-

Must have edit_post permission for the channel the post is in.

-
Authorizations:
bearerAuth
path Parameters
post_id
required
string

ID of the post to update

-
Request Body schema: application/json

Post object that is to be updated

-
id
required
string

ID of the post to update

-
is_pinned
boolean

Set to true to pin the post to the channel it is in

-
message
string

The message text of the post

-
has_reactions
boolean

Set to true if the post has reactions to it

-
props
string

A general JSON property bag to attach to the post

-

Responses

200

Post update successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
put /posts/{post_id}
http://your-mattermost-url.com/api/v4/posts/{post_id}
https://your-mattermost-url.com/api/v4/posts/{post_id}

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "is_pinned": true,
  • "message": "string",
  • "has_reactions": true,
  • "props": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "edit_at": 0,
  • "user_id": "string",
  • "channel_id": "string",
  • "root_id": "string",
  • "parent_id": "string",
  • "original_id": "string",
  • "message": "string",
  • "type": "string",
  • "props": { },
  • "hashtag": "string",
  • "filenames":
    [
    ],
  • "file_ids":
    [
    ],
  • "pending_post_id": "string",
  • "metadata":
    {
    }
}

Mark as unread from a post.

Mark a channel as being unread from a given post.

-
Permissions
-

Must have read_channel permission for the channel the post is in or if the channel is public, have the read_public_channels permission for the team. -Must have edit_other_users permission if the user is not the one marking the post for himself.

-

Minimum server version: 5.18

-
Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

-
post_id
required
string

Post GUID

-

Responses

200

Post marked as unread successfully

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
post /user/{user_id}/posts/{post_id}/set_unread
http://your-mattermost-url.com/api/v4/user/{user_id}/posts/{post_id}/set_unread
https://your-mattermost-url.com/api/v4/user/{user_id}/posts/{post_id}/set_unread

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "team_id": "string",
  • "channel_id": "string",
  • "msg_count": 0,
  • "mention_count": 0,
  • "last_viewed_at": 0
}

Patch a post

Partially update a post by providing only the fields you want to update. Omitted fields will not be updated. The fields that can be updated are defined in the request body, all other provided fields will be ignored.

-
Permissions
-

Must have the edit_post permission.

-
Authorizations:
bearerAuth
path Parameters
post_id
required
string

Post GUID

-
Request Body schema: application/json

Post object that is to be updated

-
is_pinned
boolean

Set to true to pin the post to the channel it is in

-
message
string

The message text of the post

-
file_ids
Array of strings

The list of files attached to this post

-
has_reactions
boolean

Set to true if the post has reactions to it

-
props
string

A general JSON property bag to attach to the post

-

Responses

200

Post patch successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
put /posts/{post_id}/patch
http://your-mattermost-url.com/api/v4/posts/{post_id}/patch
https://your-mattermost-url.com/api/v4/posts/{post_id}/patch

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "is_pinned": true,
  • "message": "string",
  • "file_ids":
    [
    ],
  • "has_reactions": true,
  • "props": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "edit_at": 0,
  • "user_id": "string",
  • "channel_id": "string",
  • "root_id": "string",
  • "parent_id": "string",
  • "original_id": "string",
  • "message": "string",
  • "type": "string",
  • "props": { },
  • "hashtag": "string",
  • "filenames":
    [
    ],
  • "file_ids":
    [
    ],
  • "pending_post_id": "string",
  • "metadata":
    {
    }
}

Get a thread

Get a post and the rest of the posts in the same thread.

-
Permissions
-

Must have read_channel permission for the channel the post is in or if the channel is public, have the read_public_channels permission for the team.

-
Authorizations:
bearerAuth
path Parameters
post_id
required
string

ID of a post in the thread

-

Responses

200

Post list retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
get /posts/{post_id}/thread
http://your-mattermost-url.com/api/v4/posts/{post_id}/thread
https://your-mattermost-url.com/api/v4/posts/{post_id}/thread

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "order":
    [
    ],
  • "posts":
    {
    },
  • "next_post_id": "string",
  • "prev_post_id": "string"
}

Get a list of flagged posts

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.

-
Permissions
-

Must be user or have manage_system permission.

-
Authorizations:
bearerAuth
path Parameters
user_id
required
string

ID of the user

-
query Parameters
team_id
string

Team ID

-
channel_id
string

Channel ID

-
page
integer
Default: 0

The page to select

-
per_page
integer
Default: 60

The number of posts per page

-

Responses

200

Post list retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
get /users/{user_id}/posts/flagged
http://your-mattermost-url.com/api/v4/users/{user_id}/posts/flagged
https://your-mattermost-url.com/api/v4/users/{user_id}/posts/flagged

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Get file info for post

Gets a list of file information objects for the files attached to a post.

-
Permissions
-

Must have read_channel permission for the channel the post is in.

-
Authorizations:
bearerAuth
path Parameters
post_id
required
string

ID of the post

-

Responses

200

File info retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
get /posts/{post_id}/files/info
http://your-mattermost-url.com/api/v4/posts/{post_id}/files/info
https://your-mattermost-url.com/api/v4/posts/{post_id}/files/info

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Get posts for a channel

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.

-
Permissions
-

Must have read_channel permission for the channel.

-
Authorizations:
bearerAuth
path Parameters
channel_id
required
string

The channel ID to get the posts for

-
query Parameters
page
integer
Default: 0

The page to select

-
per_page
integer
Default: 60

The number of posts per page

-
since
integer

Provide a non-zero value in Unix time milliseconds to select posts created after that time

-
before
string

A post id to select the posts that came before this one

-
after
string

A post id to select the posts that came after this one

-

Responses

200

Post list retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
get /channels/{channel_id}/posts
http://your-mattermost-url.com/api/v4/channels/{channel_id}/posts
https://your-mattermost-url.com/api/v4/channels/{channel_id}/posts

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "order":
    [
    ],
  • "posts":
    {
    },
  • "next_post_id": "string",
  • "prev_post_id": "string"
}

Get posts around last unread

Get the oldest unread post in the channel for the given user as well as the posts around it.

-
Permissions
-

Must be logged in as the user or have edit_other_users permission, and must have read_channel permission for the channel. -Minimum server version: 5.14

-
Authorizations:
bearerAuth
path Parameters
user_id
required
string

ID of the user

-
channel_id
required
string

The channel ID to get the posts for

-
query Parameters
limit_before
integer
Default: 60

Number of posts before the last unread posts. Maximum is 200 posts if limit is set greater than that.

-
limit_after
integer
Default: 60

Number of posts after and including the last unread post. Maximum is 200 posts if limit is set greater than that.

-

Responses

200

Post list retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
get /users/{user_id}/channels/{channel_id}/posts/unread
http://your-mattermost-url.com/api/v4/users/{user_id}/channels/{channel_id}/posts/unread
https://your-mattermost-url.com/api/v4/users/{user_id}/channels/{channel_id}/posts/unread

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "order":
    [
    ],
  • "posts":
    {
    },
  • "next_post_id": "string",
  • "prev_post_id": "string"
}

Search for team posts

Search posts in the team and from the provided terms string.

-
Permissions
-

Must be authenticated and have the view_team permission.

-
Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

-
Request Body schema: application/json

The search terms and logic to use in the search.

-
terms
required
string

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
required
boolean

Set to true if an Or search should be performed vs an And search.

-
time_zone_offset
integer
Default: 0

Offset from UTC of user timezone for date searches.

-
include_deleted_channels
boolean

Set to true if deleted channels should be included in the search. (archived channels)

-
page
integer
Default: 0

The page to select. (Only works with Elasticsearch)

-
per_page
integer
Default: 60

The number of posts per page. (Only works with Elasticsearch)

-

Responses

200

Post list retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
post /teams/{team_id}/posts/search
http://your-mattermost-url.com/api/v4/teams/{team_id}/posts/search
https://your-mattermost-url.com/api/v4/teams/{team_id}/posts/search

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "terms": "string",
  • "is_or_search": true,
  • "time_zone_offset": 0,
  • "include_deleted_channels": true,
  • "page": 0,
  • "per_page": 60
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "order":
    [
    ],
  • "posts":
    {
    },
  • "matches":
    {
    }
}

Pin a post to the channel

Pin a post to a channel it is in based from the provided post id string.

-
Permissions
-

Must be authenticated and have the read_channel permission to the channel the post is in.

-
Authorizations:
bearerAuth
path Parameters
post_id
required
string

Post GUID

-

Responses

200

Pinned post successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
post /posts/{post_id}/pin
http://your-mattermost-url.com/api/v4/posts/{post_id}/pin
https://your-mattermost-url.com/api/v4/posts/{post_id}/pin

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Unpin a post to the channel

Unpin a post to a channel it is in based from the provided post id string.

-
Permissions
-

Must be authenticated and have the read_channel permission to the channel the post is in.

-
Authorizations:
bearerAuth
path Parameters
post_id
required
string

Post GUID

-

Responses

200

Unpinned post successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
post /posts/{post_id}/unpin
http://your-mattermost-url.com/api/v4/posts/{post_id}/unpin
https://your-mattermost-url.com/api/v4/posts/{post_id}/unpin

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Perform a post action

Perform a post action, which allows users to interact with integrations through posts.

-
Permissions
-

Must be authenticated and have the read_channel permission to the channel the post is in.

-
Authorizations:
bearerAuth
path Parameters
post_id
required
string

Post GUID

-
action_id
required
string

Action GUID

-

Responses

200

Post action successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
post /posts/{post_id}/actions/{action_id}
http://your-mattermost-url.com/api/v4/posts/{post_id}/actions/{action_id}
https://your-mattermost-url.com/api/v4/posts/{post_id}/actions/{action_id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

files

Endpoints for uploading and interacting with files.

-

Upload a file

Uploads a file that can later be attached to a post.

-

This request can either be a multipart/form-data request with a channel_id, files and optional -client_ids defined in the FormData, or it can be a request with the channel_id and filename -defined as query parameters with the contents of a single file in the body of the request.

-

Only multipart/form-data requests are supported by server versions up to and including 4.7. -Server versions 4.8 and higher support both types of requests.

-
Permissions
-

Must have upload_file permission.

-
Authorizations:
bearerAuth
query Parameters
channel_id
string

The ID of the channel that this file will be uploaded to

-
filename
string

The name of the file to be uploaded

-
Request Body schema: multipart/form-data
files
string <binary>

A file to be uploaded

-
channel_id
string

The ID of the channel that this file will be uploaded to

-
client_ids
string

A unique identifier for the file that will be returned in the response

-

Responses

201

Corresponding lists of the provided client_ids and the metadata that has been stored in the database for each one

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
413

Content too large

-
501

Feature is disabled

-
post /files
http://your-mattermost-url.com/api/v4/files
https://your-mattermost-url.com/api/v4/files

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-file, err := os.Open("file.png")
-if err != nil {
-  fmt.Fprintf(os.Stderr, "%v\n", err)
-}
-defer file.Close();
-
-buf := bytes.NewBuffer(nil)
-io.Copy(buf, file)
-data := buf.Bytes()
-
-channelID := "4xp9fdt77pncbef59f4k1qe83o"
-filename := "file.png"
-
-fileUploadResponse, response := Client.UploadFile(data, channelID, filename)
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "file_infos":
    [
    ],
  • "client_ids":
    [
    ]
}

Get a file

Gets a file that has been uploaded previously.

-
Permissions
-

Must have read_channel permission or be uploader of the file.

-
Authorizations:
bearerAuth
path Parameters
file_id
required
string

The ID of the file to get

-

Responses

400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
501

Feature is disabled

-
get /files/{file_id}
http://your-mattermost-url.com/api/v4/files/{file_id}
https://your-mattermost-url.com/api/v4/files/{file_id}

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-fileID := "4xp9fdt77pncbef59f4k1qe83o"
-
-data, resp := Client.GetFile(fileID)
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

Get a file's thumbnail

Gets a file's thumbnail.

-
Permissions
-

Must have read_channel permission or be uploader of the file.

-
Authorizations:
bearerAuth
path Parameters
file_id
required
string

The ID of the file to get

-

Responses

400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
501

Feature is disabled

-
get /files/{file_id}/thumbnail
http://your-mattermost-url.com/api/v4/files/{file_id}/thumbnail
https://your-mattermost-url.com/api/v4/files/{file_id}/thumbnail

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-fileID := "4xp9fdt77pncbef59f4k1qe83o"
-
-data, resp := Client.GetFileThumbnail(fileID)
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

Get a file's preview

Gets a file's preview.

-
Permissions
-

Must have read_channel permission or be uploader of the file.

-
Authorizations:
bearerAuth
path Parameters
file_id
required
string

The ID of the file to get

-

Responses

400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
501

Feature is disabled

-
get /files/{file_id}/preview
http://your-mattermost-url.com/api/v4/files/{file_id}/preview
https://your-mattermost-url.com/api/v4/files/{file_id}/preview

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-fileID := "4xp9fdt77pncbef59f4k1qe83o"
-
-data, resp := Client.GetFilePreview(fileID)
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

Get a public file link

Gets a public link for a file that can be accessed without logging into Mattermost.

-
Permissions
-

Must have read_channel permission or be uploader of the file.

-
Authorizations:
bearerAuth
path Parameters
file_id
required
string

The ID of the file to get a link for

-

Responses

200

A publicly accessible link to the given file

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
501

Feature is disabled

-
get /files/{file_id}/link
http://your-mattermost-url.com/api/v4/files/{file_id}/link
https://your-mattermost-url.com/api/v4/files/{file_id}/link

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-fileID := "4xp9fdt77pncbef59f4k1qe83o"
-
-data, resp := Client.GetFileLink(fileID)
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "link": "string"
}

Get metadata for a file

Gets a file's info.

-
Permissions
-

Must have read_channel permission or be uploader of the file.

-
Authorizations:
bearerAuth
path Parameters
file_id
required
string

The ID of the file info to get

-

Responses

200

The stored metadata for the given file

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
501

Feature is disabled

-
get /files/{file_id}/info
http://your-mattermost-url.com/api/v4/files/{file_id}/info
https://your-mattermost-url.com/api/v4/files/{file_id}/info

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-fileID := "4xp9fdt77pncbef59f4k1qe83o"
-
-info, resp := Client.GetFileInfo(fileID)
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "user_id": "string",
  • "post_id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "name": "string",
  • "extension": "string",
  • "size": 0,
  • "mime_type": "string",
  • "width": 0,
  • "height": 0,
  • "has_preview_image": true
}

preferences

Endpoints for saving and modifying user preferences.

-

Get the user's preferences

Get a list of the user's preferences.

-
Permissions
-

Must be logged in as the user being updated or have the edit_other_users permission.

-
Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

-

Responses

200

User preferences retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
get /users/{user_id}/preferences
http://your-mattermost-url.com/api/v4/users/{user_id}/preferences
https://your-mattermost-url.com/api/v4/users/{user_id}/preferences

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Save the user's preferences

Save a list of the user's preferences.

-
Permissions
-

Must be logged in as the user being updated or have the edit_other_users permission.

-
Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

-
Request Body schema: application/json

List of preference objects

-
Array
user_id
string

The ID of the user that owns this preference

-
category
string
name
string
value
string

Responses

200

User preferences saved successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
put /users/{user_id}/preferences
http://your-mattermost-url.com/api/v4/users/{user_id}/preferences
https://your-mattermost-url.com/api/v4/users/{user_id}/preferences

Request samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Delete user's preferences

Delete a list of the user's preferences.

-
Permissions
-

Must be logged in as the user being updated or have the edit_other_users permission.

-
Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

-
Request Body schema: application/json

List of preference objects

-
Array
user_id
string

The ID of the user that owns this preference

-
category
string
name
string
value
string

Responses

200

User preferences saved successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
post /users/{user_id}/preferences/delete
http://your-mattermost-url.com/api/v4/users/{user_id}/preferences/delete
https://your-mattermost-url.com/api/v4/users/{user_id}/preferences/delete

Request samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

List a user's preferences by category

Lists the current user's stored preferences in the given category.

-
Permissions
-

Must be logged in as the user being updated or have the edit_other_users permission.

-
Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

-
category
required
string

The category of a group of preferences

-

Responses

200

A list of all of the current user's preferences in the given category

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
get /users/{user_id}/preferences/{category}
http://your-mattermost-url.com/api/v4/users/{user_id}/preferences/{category}
https://your-mattermost-url.com/api/v4/users/{user_id}/preferences/{category}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Get a specific user preference

Gets a single preference for the current user with the given category and name.

-
Permissions
-

Must be logged in as the user being updated or have the edit_other_users permission.

-
Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

-
category
required
string

The category of a group of preferences

-
preference_name
required
string

The name of the preference

-

Responses

200

A single preference for the current user in the current categorylist of all of the current user's preferences in the given category.

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
get /users/{user_id}/preferences/{category}/name/{preference_name}
http://your-mattermost-url.com/api/v4/users/{user_id}/preferences/{category}/name/{preference_name}
https://your-mattermost-url.com/api/v4/users/{user_id}/preferences/{category}/name/{preference_name}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "user_id": "string",
  • "category": "string",
  • "name": "string",
  • "value": "string"
}

status

Endpoints for getting and updating user statuses.

-

Get user status

Get user status by id from the server.

-
Permissions
-

Must be authenticated.

-
Authorizations:
bearerAuth
path Parameters
user_id
required
string

User ID

-

Responses

200

User status retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
get /users/{user_id}/status
http://your-mattermost-url.com/api/v4/users/{user_id}/status
https://your-mattermost-url.com/api/v4/users/{user_id}/status

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "user_id": "string",
  • "status": "string",
  • "manual": true,
  • "last_activity_at": 0
}

Update user status

Manually set a user's status. When setting a user's status, the status will remain that value until set "online" again, which will return the status to being automatically updated based on user activity.

-
Permissions
-

Must have edit_other_users permission for the team.

-
Authorizations:
bearerAuth
path Parameters
user_id
required
string

User ID

-
Request Body schema: application/json

Status object that is to be updated

-
user_id
required
string

User ID

-
status
required
string

User status, can be online, away, offline and dnd

-

Responses

200

User status update successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
put /users/{user_id}/status
http://your-mattermost-url.com/api/v4/users/{user_id}/status
https://your-mattermost-url.com/api/v4/users/{user_id}/status

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "user_id": "string",
  • "status": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "user_id": "string",
  • "status": "string",
  • "manual": true,
  • "last_activity_at": 0
}

Get user statuses by id

Get a list of user statuses by id from the server.

-
Permissions
-

Must be authenticated.

-
Authorizations:
bearerAuth
Request Body schema: application/json

List of user ids to fetch

-
Array
string

Responses

200

User statuses retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
post /users/status/ids
http://your-mattermost-url.com/api/v4/users/status/ids
https://your-mattermost-url.com/api/v4/users/status/ids

Request samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • "string"
]

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

emoji

Endpoints for creating, getting and interacting with emojis.

-

Create a custom emoji

Create a custom emoji for the team.

-
Permissions
-

Must be authenticated.

-
Authorizations:
bearerAuth
Request Body schema: multipart/form-data
image
required
string <binary>

A file to be uploaded

-
emoji
required
string

A JSON object containing a name field with the name of the emoji and a creator_id field with the id of the authenticated user.

-

Responses

201

Emoji creation successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
413

Content too large

-
501

Feature is disabled

-
post /emoji
http://your-mattermost-url.com/api/v4/emoji
https://your-mattermost-url.com/api/v4/emoji

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "creator_id": "string",
  • "name": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0
}

Get a list of custom emoji

Get a page of metadata for custom emoji on the system. Since server version 4.7, sort using the sort query parameter.

-
Permissions
-

Must be authenticated.

-
Authorizations:
bearerAuth
query Parameters
page
integer
Default: 0

The page to select.

-
per_page
integer
Default: 60

The number of users per page.

-
sort
string
Default: ""

Either blank for no sorting or "name" to sort by emoji names. Minimum server version for sorting is 4.7.

-

Responses

200

Emoji list retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
501

Feature is disabled

-
get /emoji
http://your-mattermost-url.com/api/v4/emoji
https://your-mattermost-url.com/api/v4/emoji

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "creator_id": "string",
  • "name": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0
}

Get a custom emoji

Get some metadata for a custom emoji.

-
Permissions
-

Must be authenticated.

-
Authorizations:
bearerAuth
path Parameters
emoji_id
required
string

Emoji GUID

-

Responses

200

Emoji retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
404

Resource not found

-
501

Feature is disabled

-
get /emoji/{emoji_id}
http://your-mattermost-url.com/api/v4/emoji/{emoji_id}
https://your-mattermost-url.com/api/v4/emoji/{emoji_id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "creator_id": "string",
  • "name": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0
}

Delete a custom emoji

Delete a custom emoji.

-
Permissions
-

Must have the manage_team or manage_system permissions or be the user who created the emoji.

-
Authorizations:
bearerAuth
path Parameters
emoji_id
required
string

Emoji GUID

-

Responses

200

Emoji delete successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
501

Feature is disabled

-
delete /emoji/{emoji_id}
http://your-mattermost-url.com/api/v4/emoji/{emoji_id}
https://your-mattermost-url.com/api/v4/emoji/{emoji_id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "creator_id": "string",
  • "name": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0
}

Get a custom emoji by name

Get some metadata for a custom emoji using its name.

-
Permissions
-

Must be authenticated.

-

Minimum server version: 4.7

-
Authorizations:
bearerAuth
path Parameters
emoji_name
required
string

Emoji name

-

Responses

200

Emoji retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
404

Resource not found

-
501

Feature is disabled

-
get /emoji/name/{emoji_name}
http://your-mattermost-url.com/api/v4/emoji/name/{emoji_name}
https://your-mattermost-url.com/api/v4/emoji/name/{emoji_name}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "creator_id": "string",
  • "name": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0
}

Get custom emoji image

Get the image for a custom emoji.

-
Permissions
-

Must be authenticated.

-
Authorizations:
bearerAuth
path Parameters
emoji_id
required
string

Emoji GUID

-

Responses

200

Emoji image retrieval successful

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
500

Something went wrong with the server

-
501

Feature is disabled

-
get /emoji/{emoji_id}/image
http://your-mattermost-url.com/api/v4/emoji/{emoji_id}/image
https://your-mattermost-url.com/api/v4/emoji/{emoji_id}/image

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

Search custom emoji

Search for custom emoji by name based on search criteria provided in the request body. A maximum of 200 results are returned.

-
Permissions
-

Must be authenticated.

-

Minimum server version: 4.7

-
Authorizations:
bearerAuth
Request Body schema: application/json

Search criteria

-
term
required
string

The term to match against the emoji name.

-
prefix_only
string

Set to only search for names starting with the search term.

-

Responses

200

Emoji list retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
501

Feature is disabled

-
post /emoji/search
http://your-mattermost-url.com/api/v4/emoji/search
https://your-mattermost-url.com/api/v4/emoji/search

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "term": "string",
  • "prefix_only": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Autocomplete custom emoji

Get a list of custom emoji with names starting with or matching the provided name. Returns a maximum of 100 results.

-
Permissions
-

Must be authenticated.

-

Minimum server version: 4.7

-
Authorizations:
bearerAuth
query Parameters
name
required
string

The emoji name to search.

-

Responses

200

Emoji list retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
501

Feature is disabled

-
get /emoji/autocomplete
http://your-mattermost-url.com/api/v4/emoji/autocomplete
https://your-mattermost-url.com/api/v4/emoji/autocomplete

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "creator_id": "string",
  • "name": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0
}

reactions

Endpoints for creating, getting and removing emoji reactions.

-

Create a reaction

Create a reaction.

-
Permissions
-

Must have read_channel permission for the channel the post is in.

-
Authorizations:
bearerAuth
Request Body schema: application/json

The user's reaction with its post_id, user_id, and emoji_name fields set

-
user_id
string

The ID of the user that made this reaction

-
post_id
string

The ID of the post to which this reaction was made

-
emoji_name
string

The name of the emoji that was used for this reaction

-
create_at
integer <int64>

The time in milliseconds this reaction was made

-

Responses

201

Reaction creation successful

-
400

Invalid or missing parameters in URL or request body

-
403

Do not have appropriate permissions

-
post /reactions
http://your-mattermost-url.com/api/v4/reactions
https://your-mattermost-url.com/api/v4/reactions

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "user_id": "string",
  • "post_id": "string",
  • "emoji_name": "string",
  • "create_at": 0
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "user_id": "string",
  • "post_id": "string",
  • "emoji_name": "string",
  • "create_at": 0
}

Get a list of reactions to a post

Get a list of reactions made by all users to a given post.

-
Permissions
-

Must have read_channel permission for the channel the post is in.

-
Authorizations:
bearerAuth
path Parameters
post_id
required
string

ID of a post

-

Responses

200

List reactions retrieve successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
get /posts/{post_id}/reactions
http://your-mattermost-url.com/api/v4/posts/{post_id}/reactions
https://your-mattermost-url.com/api/v4/posts/{post_id}/reactions

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Remove a reaction from a post

Deletes a reaction made by a user from the given post.

-
Permissions
-

Must be user or have manage_system permission.

-
Authorizations:
bearerAuth
path Parameters
user_id
required
string

ID of the user

-
post_id
required
string

ID of the post

-
emoji_name
required
string

emoji name

-

Responses

200

Reaction deletion successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
delete /users/{user_id}/posts/{post_id}/reactions/{emoji_name}
http://your-mattermost-url.com/api/v4/users/{user_id}/posts/{post_id}/reactions/{emoji_name}
https://your-mattermost-url.com/api/v4/users/{user_id}/posts/{post_id}/reactions/{emoji_name}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Bulk get the reaction for posts

Get a list of reactions made by all users to a given post.

-
Permissions
-

Must have read_channel permission for the channel the post is in.

-

Minimum server version: 5.8

-
Authorizations:
bearerAuth
Request Body schema: application/json

Array of post IDs

-
Array
string

Responses

200

Reactions retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
post /posts/ids/reactions
http://your-mattermost-url.com/api/v4/posts/ids/reactions
https://your-mattermost-url.com/api/v4/posts/ids/reactions

Request samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • "string"
]

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "property1":
    [
    ],
  • "property2":
    [
    ]
}

webhooks

Endpoints for creating, getting and updating webhooks.

-

Create an incoming webhook

Create an incoming webhook for a channel.

-
Permissions
-

manage_webhooks for the channel the webhook is in.

-
Authorizations:
bearerAuth
Request Body schema: application/json

Incoming webhook to be created

-
channel_id
required
string

The ID of a public channel or private group that receives the webhook payloads.

-
display_name
string

The display name for this incoming webhook

-
description
string

The description for this incoming webhook

-
username
string

The username this incoming webhook will post as.

-
icon_url
string

The profile picture this incoming webhook will use when posting.

-

Responses

201

Incoming webhook creation successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
post /hooks/incoming
http://your-mattermost-url.com/api/v4/hooks/incoming
https://your-mattermost-url.com/api/v4/hooks/incoming

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "channel_id": "string",
  • "display_name": "string",
  • "description": "string",
  • "username": "string",
  • "icon_url": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "channel_id": "string",
  • "description": "string",
  • "display_name": "string"
}

List incoming webhooks

Get a page of a list of incoming webhooks. Optionally filter for a specific team using query parameters.

-
Permissions
-

manage_webhooks for the system or manage_webhooks for the specific team.

-
Authorizations:
bearerAuth
query Parameters
page
integer
Default: 0

The page to select.

-
per_page
integer
Default: 60

The number of hooks per page.

-
team_id
string

The ID of the team to get hooks for.

-

Responses

200

Incoming webhooks retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
get /hooks/incoming
http://your-mattermost-url.com/api/v4/hooks/incoming
https://your-mattermost-url.com/api/v4/hooks/incoming

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Get an incoming webhook

Get an incoming webhook given the hook id.

-
Permissions
-

manage_webhooks for system or manage_webhooks for the specific team or manage_webhooks for the channel.

-
Authorizations:
bearerAuth
path Parameters
hook_id
required
string

Incoming Webhook GUID

-

Responses

200

Webhook retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
get /hooks/incoming/{hook_id}
http://your-mattermost-url.com/api/v4/hooks/incoming/{hook_id}
https://your-mattermost-url.com/api/v4/hooks/incoming/{hook_id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "channel_id": "string",
  • "description": "string",
  • "display_name": "string"
}

Update an incoming webhook

Update an incoming webhook given the hook id.

-
Permissions
-

manage_webhooks for system or manage_webhooks for the specific team or manage_webhooks for the channel.

-
Authorizations:
bearerAuth
path Parameters
hook_id
required
string

Incoming Webhook GUID

-
Request Body schema: application/json

Incoming webhook to be updated

-
hook_id
string

Incoming webhook GUID

-
channel_id
required
string

The ID of a public channel or private group that receives the webhook payloads.

-
display_name
required
string

The display name for this incoming webhook

-
description
required
string

The description for this incoming webhook

-
username
string

The username this incoming webhook will post as.

-
icon_url
string

The profile picture this incoming webhook will use when posting.

-

Responses

200

Webhook update successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
put /hooks/incoming/{hook_id}
http://your-mattermost-url.com/api/v4/hooks/incoming/{hook_id}
https://your-mattermost-url.com/api/v4/hooks/incoming/{hook_id}

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "hook_id": "string",
  • "channel_id": "string",
  • "display_name": "string",
  • "description": "string",
  • "username": "string",
  • "icon_url": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "channel_id": "string",
  • "description": "string",
  • "display_name": "string"
}

Create an outgoing webhook

Create an outgoing webhook for a team.

-
Permissions
-

manage_webhooks for the team the webhook is in.

-
Authorizations:
bearerAuth
Request Body schema: application/json

Outgoing webhook to be created

-
team_id
required
string

The ID of the team that the webhook watchs

-
channel_id
string

The ID of a public channel that the webhook watchs

-
description
string

The description for this outgoing webhook

-
display_name
required
string

The display name for this outgoing webhook

-
trigger_words
required
Array of strings

List of words for the webhook to trigger on

-
trigger_when
integer

When to trigger the webhook, 0 when a trigger word is present at all and 1 if the message starts with a trigger word

-
callback_urls
required
Array of strings

The URLs to POST the payloads to when the webhook is triggered

-
content_type
string
Default: "application/x-www-form-urlencoded"

The format to POST the data in, either application/json or application/x-www-form-urlencoded

-

Responses

201

Outgoing webhook creation successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
post /hooks/outgoing
http://your-mattermost-url.com/api/v4/hooks/outgoing
https://your-mattermost-url.com/api/v4/hooks/outgoing

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "team_id": "string",
  • "channel_id": "string",
  • "description": "string",
  • "display_name": "string",
  • "trigger_words":
    [
    ],
  • "trigger_when": 0,
  • "callback_urls":
    [
    ],
  • "content_type": "application/x-www-form-urlencoded"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "creator_id": "string",
  • "team_id": "string",
  • "channel_id": "string",
  • "description": "string",
  • "display_name": "string",
  • "trigger_words":
    [
    ],
  • "trigger_when": 0,
  • "callback_urls":
    [
    ],
  • "content_type": "application/x-www-form-urlencoded"
}

List outgoing webhooks

Get a page of a list of outgoing webhooks. Optionally filter for a specific team or channel using query parameters.

-
Permissions
-

manage_webhooks for the system or manage_webhooks for the specific team/channel.

-
Authorizations:
bearerAuth
query Parameters
page
integer
Default: 0

The page to select.

-
per_page
integer
Default: 60

The number of hooks per page.

-
team_id
string

The ID of the team to get hooks for.

-
channel_id
string

The ID of the channel to get hooks for.

-

Responses

200

Outgoing webhooks retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
get /hooks/outgoing
http://your-mattermost-url.com/api/v4/hooks/outgoing
https://your-mattermost-url.com/api/v4/hooks/outgoing

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Get an outgoing webhook

Get an outgoing webhook given the hook id.

-
Permissions
-

manage_webhooks for system or manage_webhooks for the specific team or manage_webhooks for the channel.

-
Authorizations:
bearerAuth
path Parameters
hook_id
required
string

Outgoing webhook GUID

-

Responses

200

Outgoing webhook retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
get /hooks/outgoing/{hook_id}
http://your-mattermost-url.com/api/v4/hooks/outgoing/{hook_id}
https://your-mattermost-url.com/api/v4/hooks/outgoing/{hook_id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "creator_id": "string",
  • "team_id": "string",
  • "channel_id": "string",
  • "description": "string",
  • "display_name": "string",
  • "trigger_words":
    [
    ],
  • "trigger_when": 0,
  • "callback_urls":
    [
    ],
  • "content_type": "application/x-www-form-urlencoded"
}

Delete an outgoing webhook

Delete an outgoing webhook given the hook id.

-
Permissions
-

manage_webhooks for system or manage_webhooks for the specific team or manage_webhooks for the channel.

-
Authorizations:
bearerAuth
path Parameters
hook_id
required
string

Outgoing webhook GUID

-

Responses

200

Webhook deletion successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
delete /hooks/outgoing/{hook_id}
http://your-mattermost-url.com/api/v4/hooks/outgoing/{hook_id}
https://your-mattermost-url.com/api/v4/hooks/outgoing/{hook_id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Update an outgoing webhook

Update an outgoing webhook given the hook id.

-
Permissions
-

manage_webhooks for system or manage_webhooks for the specific team or manage_webhooks for the channel.

-
Authorizations:
bearerAuth
path Parameters
hook_id
required
string

outgoing Webhook GUID

-
Request Body schema: application/json

Outgoing webhook to be updated

-
hook_id
string

Outgoing webhook GUID

-
channel_id
required
string

The ID of a public channel or private group that receives the webhook payloads.

-
display_name
required
string

The display name for this incoming webhook

-
description
required
string

The description for this incoming webhook

-

Responses

200

Webhook update successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
put /hooks/outgoing/{hook_id}
http://your-mattermost-url.com/api/v4/hooks/outgoing/{hook_id}
https://your-mattermost-url.com/api/v4/hooks/outgoing/{hook_id}

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "hook_id": "string",
  • "channel_id": "string",
  • "display_name": "string",
  • "description": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "creator_id": "string",
  • "team_id": "string",
  • "channel_id": "string",
  • "description": "string",
  • "display_name": "string",
  • "trigger_words":
    [
    ],
  • "trigger_when": 0,
  • "callback_urls":
    [
    ],
  • "content_type": "application/x-www-form-urlencoded"
}

Regenerate the token for the outgoing webhook.

Regenerate the token for the outgoing webhook.

-
Permissions
-

manage_webhooks for system or manage_webhooks for the specific team or manage_webhooks for the channel.

-
Authorizations:
bearerAuth
path Parameters
hook_id
required
string

Outgoing webhook GUID

-

Responses

200

Webhook token regenerate successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
post /hooks/outgoing/{hook_id}/regen_token
http://your-mattermost-url.com/api/v4/hooks/outgoing/{hook_id}/regen_token
https://your-mattermost-url.com/api/v4/hooks/outgoing/{hook_id}/regen_token

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

commands

Endpoints for creating, getting and updating slash commands.

-

Create a command

Create a command for a team.

-
Permissions
-

manage_slash_commands for the team the command is in.

-
Authorizations:
bearerAuth
Request Body schema: application/json

command to be created

-
team_id
required
string

Team ID to where the command should be created

-
method
required
string

'P' for post request, 'G' for get request

-
trigger
required
string

Activation word to trigger the command

-
url
required
string

The URL that the command will make the request

-

Responses

201

Command creation successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
501

Feature is disabled

-
post /commands
http://your-mattermost-url.com/api/v4/commands
https://your-mattermost-url.com/api/v4/commands

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "team_id": "string",
  • "method": "string",
  • "trigger": "string",
  • "url": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "token": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "deleted_at": 0,
  • "creator_id": "string",
  • "team_id": "string",
  • "trigger": "string",
  • "method": "string",
  • "username": "string",
  • "icon_url": "string",
  • "auto_complete": true,
  • "auto_complete_desc": "string",
  • "auto_complete_hint": "string",
  • "display_name": "string",
  • "description": "string",
  • "url": "string"
}

List commands for a team

List commands for a team.

-
Permissions
-

manage_slash_commands if need list custom commands.

-
Authorizations:
bearerAuth
query Parameters
team_id
string

The team id.

-
custom_only
boolean
Default: false

To get only the custom commands. If set to false will get the custom -if the user have access plus the system commands, otherwise just the system commands.

-

Responses

200

List Commands retrieve successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
501

Feature is disabled

-
get /commands
http://your-mattermost-url.com/api/v4/commands
https://your-mattermost-url.com/api/v4/commands

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-// ListCommands
-// The second parameter is to set if you want only custom commands (true) or defaults commands (false)
-listCommands, resp := Client.ListCommands(<TEAMID>, true)
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

List autocomplete commands

List autocomplete commands in the team.

-
Permissions
-

view_team for the team.

-
Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

-

Responses

200

Autocomplete commands retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
get /teams/{team_id}/commands/autocomplete
http://your-mattermost-url.com/api/v4/teams/{team_id}/commands/autocomplete
https://your-mattermost-url.com/api/v4/teams/{team_id}/commands/autocomplete

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-// ListAutocompleteCommands
-listCommands, resp := Client.ListAutocompleteCommands(<TEAMID>)
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Get a command

Get a command definition based on command id string.

-
Permissions
-

Must have manage_slash_commands permission for the team the command is in.

-

Minimum server version: 5.22

-
Authorizations:
bearerAuth
path Parameters
command_id
required
string

ID of the command to get

-

Responses

200

Command get successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
404

Resource not found

-
get /commands/{command_id}
http://your-mattermost-url.com/api/v4/commands/{command_id}
https://your-mattermost-url.com/api/v4/commands/{command_id}

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-// GetCommand
-cmd, resp := Client.GetCommand(<COMMANDID>)
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "token": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "deleted_at": 0,
  • "creator_id": "string",
  • "team_id": "string",
  • "trigger": "string",
  • "method": "string",
  • "username": "string",
  • "icon_url": "string",
  • "auto_complete": true,
  • "auto_complete_desc": "string",
  • "auto_complete_hint": "string",
  • "display_name": "string",
  • "description": "string",
  • "url": "string"
}

Update a command

Update a single command based on command id string and Command struct.

-
Permissions
-

Must have manage_slash_commands permission for the team the command is in.

-
Authorizations:
bearerAuth
path Parameters
command_id
required
string

ID of the command to update

-
Request Body schema: application/json
id
string

The ID of the slash command

-
token
string

The token which is used to verify the source of the payload

-
create_at
integer

The time in milliseconds the command was created

-
update_at
integer <int64>

The time in milliseconds the command was last updated

-
deleted_at
integer <int64>

The time in milliseconds the command was deleted, 0 if never deleted

-
creator_id
string

The user id for the commands creator

-
team_id
string

The team id for which this command is configured

-
trigger
string

The string that triggers this command

-
method
string

Is the trigger done with HTTP Get ('G') or HTTP Post ('P')

-
username
string

What is the username for the response post

-
icon_url
string

The url to find the icon for this users avatar

-
auto_complete
boolean

Use auto complete for this command

-
auto_complete_desc
string

The description for this command shown when selecting the command

-
auto_complete_hint
string

The hint for this command

-
display_name
string

Display name for the command

-
description
string

Description for this command

-
url
string

The URL that is triggered

-

Responses

200

Command updated successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
put /commands/{command_id}
http://your-mattermost-url.com/api/v4/commands/{command_id}
https://your-mattermost-url.com/api/v4/commands/{command_id}

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "token": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "deleted_at": 0,
  • "creator_id": "string",
  • "team_id": "string",
  • "trigger": "string",
  • "method": "string",
  • "username": "string",
  • "icon_url": "string",
  • "auto_complete": true,
  • "auto_complete_desc": "string",
  • "auto_complete_hint": "string",
  • "display_name": "string",
  • "description": "string",
  • "url": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "token": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "deleted_at": 0,
  • "creator_id": "string",
  • "team_id": "string",
  • "trigger": "string",
  • "method": "string",
  • "username": "string",
  • "icon_url": "string",
  • "auto_complete": true,
  • "auto_complete_desc": "string",
  • "auto_complete_hint": "string",
  • "display_name": "string",
  • "description": "string",
  • "url": "string"
}

Delete a command

Delete a command based on command id string.

-
Permissions
-

Must have manage_slash_commands permission for the team the command is in.

-
Authorizations:
bearerAuth
path Parameters
command_id
required
string

ID of the command to delete

-

Responses

200

Command deletion successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
delete /commands/{command_id}
http://your-mattermost-url.com/api/v4/commands/{command_id}
https://your-mattermost-url.com/api/v4/commands/{command_id}

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-// DeleteCommand
-ok, resp := Client.DeleteCommand(<COMMANDID>)
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Move a command

Move a command to a different team based on command id string.

-
Permissions
-

Must have manage_slash_commands permission for the team the command is currently in and the destination team.

-

Minimum server version: 5.22

-
Authorizations:
bearerAuth
path Parameters
command_id
required
string

ID of the command to move

-
Request Body schema: application/json
team_id
string

Destination teamId

-

Responses

200

Command move successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
put /commands/{command_id}/move
http://your-mattermost-url.com/api/v4/commands/{command_id}/move
https://your-mattermost-url.com/api/v4/commands/{command_id}/move

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "team_id": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Generate a new token

Generate a new token for the command based on command id string.

-
Permissions
-

Must have manage_slash_commands permission for the team the command is in.

-
Authorizations:
bearerAuth
path Parameters
command_id
required
string

ID of the command to generate the new token

-

Responses

200

Token generation successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
put /commands/{command_id}/regen_token
http://your-mattermost-url.com/api/v4/commands/{command_id}/regen_token
https://your-mattermost-url.com/api/v4/commands/{command_id}/regen_token

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-// RegenCommandToken
-newToken, resp := Client.RegenCommandToken(<COMMANDID>)
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "token": "string"
}

Execute a command

Execute a command on a team.

-
Permissions
-

Must have use_slash_commands permission for the team the command is in.

-
Authorizations:
bearerAuth
Request Body schema: application/json

command to be executed

-
channel_id
required
string

Channel Id where the command will execute

-
command
required
string

The slash command to execute

-

Responses

200

Command execution successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
501

Feature is disabled

-
post /commands/execute
http://your-mattermost-url.com/api/v4/commands/execute
https://your-mattermost-url.com/api/v4/commands/execute

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "channel_id": "string",
  • "command": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "ResponseType": "string",
  • "Text": "string",
  • "Username": "string",
  • "IconURL": "string",
  • "GotoLocation": "string",
  • "Attachments":
    [
    ]
}

OpenGraph

Endpoint for getting Open Graph metadata.

-

Get open graph metadata for url

Get Open Graph Metadata for a specif URL. Use the Open Graph protocol to get some generic metadata about a URL. Used for creating link previews.

-

Minimum server version: 3.10

-
Permissions
-

No permission required but must be logged in.

-
Authorizations:
bearerAuth
Request Body schema: application/json
url
required
string

The URL to get Open Graph Metadata.

-

Responses

200

Open Graph retrieval successful

-
501

Feature is disabled

-
post /opengraph
http://your-mattermost-url.com/api/v4/opengraph
https://your-mattermost-url.com/api/v4/opengraph

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "url": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "type": "string",
  • "url": "string",
  • "title": "string",
  • "description": "string",
  • "determiner": "string",
  • "site_name": "string",
  • "locale": "string",
  • "locales_alternate":
    [
    ],
  • "images":
    [
    ],
  • "videos":
    [
    ],
  • "audios":
    [
    ],
  • "article":
    {
    },
  • "book":
    {
    },
  • "profile":
    {
    }
}

system

General endpoints for interacting with the server, such as configuration and logging.

-

Check system health

Check if the server is up and healthy based on the configuration setting GoRoutineHealthThreshold. If GoRoutineHealthThreshold and the number of goroutines on the server exceeds that threshold the server is considered unhealthy. If GoRoutineHealthThreshold is not set or the number of goroutines is below the threshold the server is considered healthy. -Minimum server version: 3.10

-
Permissions
-

Must be logged in.

-
Authorizations:
bearerAuth

Responses

200

Status of the system

-
500

Something went wrong with the server

-
get /system/ping
http://your-mattermost-url.com/api/v4/system/ping
https://your-mattermost-url.com/api/v4/system/ping

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-// GetPing
-status, resp := Client.GetPing()
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Recycle database connections

Recycle database connections by closing and reconnecting all connections to master and read replica databases.

-
Permissions
-

Must have manage_system permission.

-
Authorizations:
bearerAuth

Responses

200

Database recycle successful

-
403

Do not have appropriate permissions

-
post /database/recycle
http://your-mattermost-url.com/api/v4/database/recycle
https://your-mattermost-url.com/api/v4/database/recycle

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-ok, resp := Client.DatabaseRecycle()
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Send a test email

Send a test email to make sure you have your email settings configured correctly. Optionally provide a configuration in the request body to test. If no valid configuration is present in the request body the current server configuration will be tested.

-
Permissions
-

Must have manage_system permission.

-
Authorizations:
bearerAuth
Request Body schema: application/json

Mattermost configuration

-
ServiceSettings
object
TeamSettings
object
SqlSettings
object
LogSettings
object
PasswordSettings
object
FileSettings
object
EmailSettings
object
RateLimitSettings
object
PrivacySettings
object
SupportSettings
object
GitLabSettings
object
GoogleSettings
object
Office365Settings
object
LdapSettings
object
ComplianceSettings
object
LocalizationSettings
object
SamlSettings
object
NativeAppSettings
object
ClusterSettings
object
MetricsSettings
object
AnalyticsSettings
object

Responses

200

Email successful sent

-
403

Do not have appropriate permissions

-
500

Something went wrong with the server

-
post /email/test
http://your-mattermost-url.com/api/v4/email/test
https://your-mattermost-url.com/api/v4/email/test

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "ServiceSettings":
    {
    },
  • "TeamSettings":
    {
    },
  • "SqlSettings":
    {
    },
  • "LogSettings":
    {
    },
  • "PasswordSettings":
    {
    },
  • "FileSettings":
    {
    },
  • "EmailSettings":
    {
    },
  • "RateLimitSettings":
    {
    },
  • "PrivacySettings":
    {
    },
  • "SupportSettings":
    {
    },
  • "GitLabSettings":
    {
    },
  • "GoogleSettings":
    {
    },
  • "Office365Settings":
    {
    },
  • "LdapSettings":
    {
    },
  • "ComplianceSettings":
    {
    },
  • "LocalizationSettings":
    {
    },
  • "SamlSettings":
    {
    },
  • "NativeAppSettings":
    {
    },
  • "ClusterSettings":
    {
    },
  • "MetricsSettings":
    {
    },
  • "AnalyticsSettings":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Checks the validity of a Site URL

Sends a Ping request to the mattermost server using the specified Site URL.

-
Permissions
-

Must have manage_system permission.

-

Minimum server version: 5.16

-
Authorizations:
bearerAuth
Request Body schema: application/json
site_url
required
string

The Site URL to test

-

Responses

200

Site URL is valid

-
400

Invalid or missing parameters in URL or request body

-
403

Do not have appropriate permissions

-
500

Something went wrong with the server

-
post /site_url/test
http://your-mattermost-url.com/api/v4/site_url/test
https://your-mattermost-url.com/api/v4/site_url/test

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "site_url": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Test AWS S3 connection

Send a test to validate if can connect to AWS S3. Optionally provide a configuration in the request body to test. If no valid configuration is present in the request body the current server configuration will be tested.

-
Permissions
-

Must have manage_system permission. -Minimum server version: 4.8

-
Authorizations:
bearerAuth
Request Body schema: application/json

Mattermost configuration

-
ServiceSettings
object
TeamSettings
object
SqlSettings
object
LogSettings
object
PasswordSettings
object
FileSettings
object
EmailSettings
object
RateLimitSettings
object
PrivacySettings
object
SupportSettings
object
GitLabSettings
object
GoogleSettings
object
Office365Settings
object
LdapSettings
object
ComplianceSettings
object
LocalizationSettings
object
SamlSettings
object
NativeAppSettings
object
ClusterSettings
object
MetricsSettings
object
AnalyticsSettings
object

Responses

200

S3 Test successful

-
403

Do not have appropriate permissions

-
500

Something went wrong with the server

-
post /file/s3_test
http://your-mattermost-url.com/api/v4/file/s3_test
https://your-mattermost-url.com/api/v4/file/s3_test

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "ServiceSettings":
    {
    },
  • "TeamSettings":
    {
    },
  • "SqlSettings":
    {
    },
  • "LogSettings":
    {
    },
  • "PasswordSettings":
    {
    },
  • "FileSettings":
    {
    },
  • "EmailSettings":
    {
    },
  • "RateLimitSettings":
    {
    },
  • "PrivacySettings":
    {
    },
  • "SupportSettings":
    {
    },
  • "GitLabSettings":
    {
    },
  • "GoogleSettings":
    {
    },
  • "Office365Settings":
    {
    },
  • "LdapSettings":
    {
    },
  • "ComplianceSettings":
    {
    },
  • "LocalizationSettings":
    {
    },
  • "SamlSettings":
    {
    },
  • "NativeAppSettings":
    {
    },
  • "ClusterSettings":
    {
    },
  • "MetricsSettings":
    {
    },
  • "AnalyticsSettings":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Get configuration

Retrieve the current server configuration

-
Permissions
-

Must have manage_system permission.

-
Authorizations:
bearerAuth

Responses

200

Configuration retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
403

Do not have appropriate permissions

-
get /config
http://your-mattermost-url.com/api/v4/config
https://your-mattermost-url.com/api/v4/config

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-// GetConfig
-config, resp := Client.GetConfig()
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "ServiceSettings":
    {
    },
  • "TeamSettings":
    {
    },
  • "SqlSettings":
    {
    },
  • "LogSettings":
    {
    },
  • "PasswordSettings":
    {
    },
  • "FileSettings":
    {
    },
  • "EmailSettings":
    {
    },
  • "RateLimitSettings":
    {
    },
  • "PrivacySettings":
    {
    },
  • "SupportSettings":
    {
    },
  • "GitLabSettings":
    {
    },
  • "GoogleSettings":
    {
    },
  • "Office365Settings":
    {
    },
  • "LdapSettings":
    {
    },
  • "ComplianceSettings":
    {
    },
  • "LocalizationSettings":
    {
    },
  • "SamlSettings":
    {
    },
  • "NativeAppSettings":
    {
    },
  • "ClusterSettings":
    {
    },
  • "MetricsSettings":
    {
    },
  • "AnalyticsSettings":
    {
    }
}

Update configuration

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.

-
Permissions
-

Must have manage_system permission.

-
Authorizations:
bearerAuth
Request Body schema: application/json

Mattermost configuration

-
ServiceSettings
object
TeamSettings
object
SqlSettings
object
LogSettings
object
PasswordSettings
object
FileSettings
object
EmailSettings
object
RateLimitSettings
object
PrivacySettings
object
SupportSettings
object
GitLabSettings
object
GoogleSettings
object
Office365Settings
object
LdapSettings
object
ComplianceSettings
object
LocalizationSettings
object
SamlSettings
object
NativeAppSettings
object
ClusterSettings
object
MetricsSettings
object
AnalyticsSettings
object

Responses

200

Configuration update successful

-
400

Invalid or missing parameters in URL or request body

-
403

Do not have appropriate permissions

-
put /config
http://your-mattermost-url.com/api/v4/config
https://your-mattermost-url.com/api/v4/config

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "ServiceSettings":
    {
    },
  • "TeamSettings":
    {
    },
  • "SqlSettings":
    {
    },
  • "LogSettings":
    {
    },
  • "PasswordSettings":
    {
    },
  • "FileSettings":
    {
    },
  • "EmailSettings":
    {
    },
  • "RateLimitSettings":
    {
    },
  • "PrivacySettings":
    {
    },
  • "SupportSettings":
    {
    },
  • "GitLabSettings":
    {
    },
  • "GoogleSettings":
    {
    },
  • "Office365Settings":
    {
    },
  • "LdapSettings":
    {
    },
  • "ComplianceSettings":
    {
    },
  • "LocalizationSettings":
    {
    },
  • "SamlSettings":
    {
    },
  • "NativeAppSettings":
    {
    },
  • "ClusterSettings":
    {
    },
  • "MetricsSettings":
    {
    },
  • "AnalyticsSettings":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "ServiceSettings":
    {
    },
  • "TeamSettings":
    {
    },
  • "SqlSettings":
    {
    },
  • "LogSettings":
    {
    },
  • "PasswordSettings":
    {
    },
  • "FileSettings":
    {
    },
  • "EmailSettings":
    {
    },
  • "RateLimitSettings":
    {
    },
  • "PrivacySettings":
    {
    },
  • "SupportSettings":
    {
    },
  • "GitLabSettings":
    {
    },
  • "GoogleSettings":
    {
    },
  • "Office365Settings":
    {
    },
  • "LdapSettings":
    {
    },
  • "ComplianceSettings":
    {
    },
  • "LocalizationSettings":
    {
    },
  • "SamlSettings":
    {
    },
  • "NativeAppSettings":
    {
    },
  • "ClusterSettings":
    {
    },
  • "MetricsSettings":
    {
    },
  • "AnalyticsSettings":
    {
    }
}

Reload configuration

Reload the configuration file to pick up on any changes made to it.

-
Permissions
-

Must have manage_system permission.

-
Authorizations:
bearerAuth

Responses

200

Configuration reload successful

-
400

Invalid or missing parameters in URL or request body

-
403

Do not have appropriate permissions

-
post /config/reload
http://your-mattermost-url.com/api/v4/config/reload
https://your-mattermost-url.com/api/v4/config/reload

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-// ReloadConfig
-ok, resp := Client.ReloadConfig()
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Get client configuration

Get a subset of the server configuration needed by the client.

-
Permissions
-

No permission required.

-
Authorizations:
bearerAuth
query Parameters
format
required
string

Must be old, other formats not implemented yet

-

Responses

200

Configuration retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
501

Feature is disabled

-
get /config/client
http://your-mattermost-url.com/api/v4/config/client
https://your-mattermost-url.com/api/v4/config/client

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-// GetOldClientConfig
-ok, resp := Client.GetOldClientConfig()
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

Get configuration made through environment variables

Retrieve a json object mirroring the server configuration where fields are set to true -if the corresponding config setting is set through an environment variable. Settings -that haven't been set through environment variables will be missing from the object.

-

Minimum server version: 4.10

-
Permissions
-

Must have manage_system permission.

-
Authorizations:
bearerAuth

Responses

200

Configuration retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
get /config/environment
http://your-mattermost-url.com/api/v4/config/environment
https://your-mattermost-url.com/api/v4/config/environment

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "ServiceSettings":
    {
    },
  • "TeamSettings":
    {
    },
  • "SqlSettings":
    {
    },
  • "LogSettings":
    {
    },
  • "PasswordSettings":
    {
    },
  • "FileSettings":
    {
    },
  • "EmailSettings":
    {
    },
  • "RateLimitSettings":
    {
    },
  • "PrivacySettings":
    {
    },
  • "SupportSettings":
    {
    },
  • "GitLabSettings":
    {
    },
  • "GoogleSettings":
    {
    },
  • "Office365Settings":
    {
    },
  • "LdapSettings":
    {
    },
  • "ComplianceSettings":
    {
    },
  • "LocalizationSettings":
    {
    },
  • "SamlSettings":
    {
    },
  • "NativeAppSettings":
    {
    },
  • "ClusterSettings":
    {
    },
  • "MetricsSettings":
    {
    },
  • "AnalyticsSettings":
    {
    }
}

Patch configuration

Submit configuration to patch. As of server version 4.8, the PluginSettings.EnableUploads setting cannot be modified by this endpoint.

-
Permissions
-

Must have manage_system permission. -Minimum server version: 5.20

-
Authorizations:
bearerAuth
Request Body schema: application/json

Mattermost configuration

-
ServiceSettings
object
TeamSettings
object
SqlSettings
object
LogSettings
object
PasswordSettings
object
FileSettings
object
EmailSettings
object
RateLimitSettings
object
PrivacySettings
object
SupportSettings
object
GitLabSettings
object
GoogleSettings
object
Office365Settings
object
LdapSettings
object
ComplianceSettings
object
LocalizationSettings
object
SamlSettings
object
NativeAppSettings
object
ClusterSettings
object
MetricsSettings
object
AnalyticsSettings
object

Responses

200

Configuration update successful

-
400

Invalid or missing parameters in URL or request body

-
403

Do not have appropriate permissions

-
put /config/patch
http://your-mattermost-url.com/api/v4/config/patch
https://your-mattermost-url.com/api/v4/config/patch

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "ServiceSettings":
    {
    },
  • "TeamSettings":
    {
    },
  • "SqlSettings":
    {
    },
  • "LogSettings":
    {
    },
  • "PasswordSettings":
    {
    },
  • "FileSettings":
    {
    },
  • "EmailSettings":
    {
    },
  • "RateLimitSettings":
    {
    },
  • "PrivacySettings":
    {
    },
  • "SupportSettings":
    {
    },
  • "GitLabSettings":
    {
    },
  • "GoogleSettings":
    {
    },
  • "Office365Settings":
    {
    },
  • "LdapSettings":
    {
    },
  • "ComplianceSettings":
    {
    },
  • "LocalizationSettings":
    {
    },
  • "SamlSettings":
    {
    },
  • "NativeAppSettings":
    {
    },
  • "ClusterSettings":
    {
    },
  • "MetricsSettings":
    {
    },
  • "AnalyticsSettings":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "ServiceSettings":
    {
    },
  • "TeamSettings":
    {
    },
  • "SqlSettings":
    {
    },
  • "LogSettings":
    {
    },
  • "PasswordSettings":
    {
    },
  • "FileSettings":
    {
    },
  • "EmailSettings":
    {
    },
  • "RateLimitSettings":
    {
    },
  • "PrivacySettings":
    {
    },
  • "SupportSettings":
    {
    },
  • "GitLabSettings":
    {
    },
  • "GoogleSettings":
    {
    },
  • "Office365Settings":
    {
    },
  • "LdapSettings":
    {
    },
  • "ComplianceSettings":
    {
    },
  • "LocalizationSettings":
    {
    },
  • "SamlSettings":
    {
    },
  • "NativeAppSettings":
    {
    },
  • "ClusterSettings":
    {
    },
  • "MetricsSettings":
    {
    },
  • "AnalyticsSettings":
    {
    }
}

Upload license file

Upload a license to enable enterprise features.

-

Minimum server version: 4.0

-
Permissions
-

Must have manage_system permission.

-
Authorizations:
bearerAuth
Request Body schema: multipart/form-data
license
required
string <binary>

The license to be uploaded

-

Responses

201

License file upload successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
413

Content too large

-
post /license
http://your-mattermost-url.com/api/v4/license
https://your-mattermost-url.com/api/v4/license

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-file, err := os.Open("<Your license file>")
-if err != nil {
-  return err
-}
-defer file.Close()
-
-data := &bytes.Buffer{}
-if _, err := io.Copy(data, file); err != nil {
-  return err
-}
-
-ok, resp := Client.UploadLicenseFile(data.Bytes())
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Remove license file

Remove the license file from the server. This will disable all enterprise features.

-

Minimum server version: 4.0

-
Permissions
-

Must have manage_system permission.

-
Authorizations:
bearerAuth

Responses

200

License removal successful

-
401

No access token provided

-
403

Do not have appropriate permissions

-
delete /license
http://your-mattermost-url.com/api/v4/license
https://your-mattermost-url.com/api/v4/license

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

Get client license

Get a subset of the server license needed by the client.

-
Permissions
-

No permission required but having the manage_system permission returns more information.

-
Authorizations:
bearerAuth
query Parameters
format
required
string

Must be old, other formats not implemented yet

-

Responses

200

License retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
501

Feature is disabled

-
get /license/client
http://your-mattermost-url.com/api/v4/license/client
https://your-mattermost-url.com/api/v4/license/client

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-// GetOldClientLicense
-license, resp := Client.GetOldClientLicense()
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

Get audits

Get a page of audits for all users on the system, selected with page and per_page query parameters.

-
Permissions
-

Must have manage_system permission.

-
Authorizations:
bearerAuth
query Parameters
page
integer
Default: 0

The page to select.

-
per_page
integer
Default: 60

The number of audits per page.

-

Responses

200

Audits retrieval successful

-
403

Do not have appropriate permissions

-
get /audits
http://your-mattermost-url.com/api/v4/audits
https://your-mattermost-url.com/api/v4/audits

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-// GetAudits
-audits, resp := Client.GetAudits(0, 100, "")
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Invalidate all the caches

Purge all the in-memory caches for the Mattermost server. This can have a temporary negative effect on performance while the caches are re-populated.

-
Permissions
-

Must have manage_system permission.

-
Authorizations:
bearerAuth

Responses

200

Caches invalidate successful

-
403

Do not have appropriate permissions

-
post /caches/invalidate
http://your-mattermost-url.com/api/v4/caches/invalidate
https://your-mattermost-url.com/api/v4/caches/invalidate

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-// InvalidateCaches
-ok, resp := Client.InvalidateCaches()
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Get logs

Get a page of server logs, selected with page and logs_per_page query parameters.

-
Permissions
-

Must have manage_system permission.

-
Authorizations:
bearerAuth
query Parameters
page
integer
Default: 0

The page to select.

-
logs_per_page
string
Default: "10000"

The number of logs per page. There is a maximum limit of 10000 logs per page.

-

Responses

200

Logs retrieval successful

-
403

Do not have appropriate permissions

-
get /logs
http://your-mattermost-url.com/api/v4/logs
https://your-mattermost-url.com/api/v4/logs

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-// GetLogs
-logs, resp := Client.GetLogs(0, 10)
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • "string"
]

Add log message

Add log messages to the server logs.

-
Permissions
-

Users with manage_system permission can log ERROR or DEBUG messages. -Logged in users can log ERROR or DEBUG messages when ServiceSettings.EnableDeveloper is true or just DEBUG messages when false. -Non-logged in users can log ERROR or DEBUG messages when ServiceSettings.EnableDeveloper is true and cannot log when false.

-
Authorizations:
bearerAuth
Request Body schema: application/json
level
required
string

The error level, ERROR or DEBUG

-
message
required
string

Message to send to the server logs

-

Responses

200

Logs sent successful

-
403

Do not have appropriate permissions

-
post /logs
http://your-mattermost-url.com/api/v4/logs
https://your-mattermost-url.com/api/v4/logs

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "level": "string",
  • "message": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{ }

Get analytics

Get some analytics data about the system. This endpoint uses the old format, the /analytics route is reserved for the new format when it gets implemented.

-

The returned JSON changes based on the name query parameter but is always key/value pairs.

-

Minimum server version: 4.0

-
Permissions
-

Must have manage_system permission.

-
Authorizations:
bearerAuth
query Parameters
name
string
Default: "standard"

Possible values are "standard", "post_counts_day", "user_counts_with_posts_day" or "extra_counts"

-
team_id
string

The team ID to filter the data by

-

Responses

200

Analytics retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
get /analytics/old
http://your-mattermost-url.com/api/v4/analytics/old
https://your-mattermost-url.com/api/v4/analytics/old

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

Set the server busy (high load) flag

Marks the server as currently having high load which disables non-critical services such as search, statuses and typing notifications.

-

Minimum server version: 5.20

-
Permissions
-

Must have manage_system permission.

-
Authorizations:
bearerAuth
query Parameters
seconds
string
Default: "3600"

Number of seconds until server is automatically marked as not busy.

-

Responses

200

Server busy flag set successfully

-
400

Invalid or missing parameters in URL or request body

-
403

Do not have appropriate permissions

-
post /server_busy
http://your-mattermost-url.com/api/v4/server_busy
https://your-mattermost-url.com/api/v4/server_busy

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-ok, resp := Client.SetServerBusy(300)
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Get server busy expiry time.

Gets the timestamp corresponding to when the server busy flag will be automatically cleared.

-

Minimum server version: 5.20

-
Permissions
-

Must have manage_system permission.

-
Authorizations:
bearerAuth

Responses

200

Server busy expires timestamp retrieved successfully

-
403

Do not have appropriate permissions

-
get /server_busy
http://your-mattermost-url.com/api/v4/server_busy
https://your-mattermost-url.com/api/v4/server_busy

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-// expires is a time.Time
-expires, resp := Client.GetServerBusyExpires()
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "busy": true,
  • "expires": 0
}

Clears the server busy (high load) flag

Marks the server as not having high load which re-enables non-critical services such as search, statuses and typing notifications.

-

Minimum server version: 5.20

-
Permissions
-

Must have manage_system permission.

-
Authorizations:
bearerAuth

Responses

200

Server busy flag cleared successfully

-
403

Do not have appropriate permissions

-
delete /server_busy
http://your-mattermost-url.com/api/v4/server_busy
https://your-mattermost-url.com/api/v4/server_busy

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-ok, resp := Client.ClearServerBusy()
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

brand

Endpoints related to custom branding and white-labeling. See our branding documentation for more information.

-

Get brand image

Get the previously uploaded brand image. Returns 404 if no brand image has been uploaded.

-
Permissions
-

No permission required.

-
Authorizations:
bearerAuth

Responses

200

Brand image retrieval successful

-
404

Resource not found

-
501

Feature is disabled

-
get /brand/image
http://your-mattermost-url.com/api/v4/brand/image
https://your-mattermost-url.com/api/v4/brand/image

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-// GetBrandImage
-img, err := Client.GetBrandImage()
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
"string"

Upload brand image

Uploads a brand image.

-
Permissions
-

Must have manage_system permission.

-
Authorizations:
bearerAuth
Request Body schema: multipart/form-data
image
required
string <binary>

The image to be uploaded

-

Responses

201

Brand image upload successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
413

Content too large

-
501

Feature is disabled

-
post /brand/image
http://your-mattermost-url.com/api/v4/brand/image
https://your-mattermost-url.com/api/v4/brand/image

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-file, err := os.Open("<Your image>")
-if err != nil {
-  return err
-}
-defer file.Close()
-
-data := &bytes.Buffer{}
-if _, err := io.Copy(data, file); err != nil {
-  return err
-}
-
-ok, resp := Client.UploadBrandImage(data.Bytes())
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Delete current brand image

Deletes the previously uploaded brand image. Returns 404 if no brand image has been uploaded.

-
Permissions
-

Must have manage_system permission. -Minimum server version: 5.6

-
Authorizations:
bearerAuth

Responses

200

Brand image succesfully deleted

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
delete /brand/image
http://your-mattermost-url.com/api/v4/brand/image
https://your-mattermost-url.com/api/v4/brand/image

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-// Delete brand image
-resp := Client.DeleteBrandImage()
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

OAuth

Endpoints for configuring and interacting with Mattermost as an OAuth 2.0 service provider.

-

Register OAuth app

Register an OAuth 2.0 client application with Mattermost as the service provider.

-
Permissions
-

Must have manage_oauth permission.

-
Authorizations:
bearerAuth
Request Body schema: application/json

OAuth application to register

-
name
required
string

The name of the client application

-
description
required
string

A short description of the application

-
icon_url
string

A URL to an icon to display with the application

-
callback_urls
required
Array of strings

A list of callback URLs for the appliation

-
homepage
required
string

A link to the website of the application

-
is_trusted
boolean

Set this to true to skip asking users for permission

-

Responses

201

App registration successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
501

Feature is disabled

-
post /oauth/apps
http://your-mattermost-url.com/api/v4/oauth/apps
https://your-mattermost-url.com/api/v4/oauth/apps

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "name": "string",
  • "description": "string",
  • "icon_url": "string",
  • "callback_urls":
    [
    ],
  • "homepage": "string",
  • "is_trusted": true
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "client_secret": "string",
  • "name": "string",
  • "description": "string",
  • "icon_url": "string",
  • "callback_urls":
    [
    ],
  • "homepage": "string",
  • "is_trusted": true,
  • "create_at": 0,
  • "update_at": 0
}

Get OAuth apps

Get a page of OAuth 2.0 client applications registered with Mattermost.

-
Permissions
-

With manage_oauth permission, the apps registered by the logged in user are returned. With manage_system_wide_oauth permission, all apps regardless of creator are returned.

-
Authorizations:
bearerAuth
query Parameters
page
integer
Default: 0

The page to select.

-
per_page
integer
Default: 60

The number of apps per page.

-

Responses

200

OAuthApp list retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
501

Feature is disabled

-
get /oauth/apps
http://your-mattermost-url.com/api/v4/oauth/apps
https://your-mattermost-url.com/api/v4/oauth/apps

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Get an OAuth app

Get an OAuth 2.0 client application registered with Mattermost.

-
Permissions
-

If app creator, must have mange_oauth permission otherwise manage_system_wide_oauth permission is required.

-
Authorizations:
bearerAuth
path Parameters
app_id
required
string

Application client id

-

Responses

200

App retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
501

Feature is disabled

-
get /oauth/apps/{app_id}
http://your-mattermost-url.com/api/v4/oauth/apps/{app_id}
https://your-mattermost-url.com/api/v4/oauth/apps/{app_id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "client_secret": "string",
  • "name": "string",
  • "description": "string",
  • "icon_url": "string",
  • "callback_urls":
    [
    ],
  • "homepage": "string",
  • "is_trusted": true,
  • "create_at": 0,
  • "update_at": 0
}

Update an OAuth app

Update an OAuth 2.0 client application based on OAuth struct.

-
Permissions
-

If app creator, must have mange_oauth permission otherwise manage_system_wide_oauth permission is required.

-
Authorizations:
bearerAuth
path Parameters
app_id
required
string

Application client id

-
Request Body schema: application/json

OAuth application to update

-
id
required
string

The id of the client application

-
name
required
string

The name of the client application

-
description
required
string

A short description of the application

-
icon_url
string

A URL to an icon to display with the application

-
callback_urls
required
Array of strings

A list of callback URLs for the appliation

-
homepage
required
string

A link to the website of the application

-
is_trusted
boolean

Set this to true to skip asking users for permission. It will be set to false if value is not provided.

-

Responses

200

App update successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
501

Feature is disabled

-
put /oauth/apps/{app_id}
http://your-mattermost-url.com/api/v4/oauth/apps/{app_id}
https://your-mattermost-url.com/api/v4/oauth/apps/{app_id}

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "icon_url": "string",
  • "callback_urls":
    [
    ],
  • "homepage": "string",
  • "is_trusted": true
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "client_secret": "string",
  • "name": "string",
  • "description": "string",
  • "icon_url": "string",
  • "callback_urls":
    [
    ],
  • "homepage": "string",
  • "is_trusted": true,
  • "create_at": 0,
  • "update_at": 0
}

Delete an OAuth app

Delete and unregister an OAuth 2.0 client application

-
Permissions
-

If app creator, must have mange_oauth permission otherwise manage_system_wide_oauth permission is required.

-
Authorizations:
bearerAuth
path Parameters
app_id
required
string

Application client id

-

Responses

200

App deletion successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
501

Feature is disabled

-
delete /oauth/apps/{app_id}
http://your-mattermost-url.com/api/v4/oauth/apps/{app_id}
https://your-mattermost-url.com/api/v4/oauth/apps/{app_id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Regenerate OAuth app secret

Regenerate the client secret for an OAuth 2.0 client application registered with Mattermost.

-
Permissions
-

If app creator, must have mange_oauth permission otherwise manage_system_wide_oauth permission is required.

-
Authorizations:
bearerAuth
path Parameters
app_id
required
string

Application client id

-

Responses

200

Secret regeneration successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
501

Feature is disabled

-
post /oauth/apps/{app_id}/regen_secret
http://your-mattermost-url.com/api/v4/oauth/apps/{app_id}/regen_secret
https://your-mattermost-url.com/api/v4/oauth/apps/{app_id}/regen_secret

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "client_secret": "string",
  • "name": "string",
  • "description": "string",
  • "icon_url": "string",
  • "callback_urls":
    [
    ],
  • "homepage": "string",
  • "is_trusted": true,
  • "create_at": 0,
  • "update_at": 0
}

Get info on an OAuth app

Get public information about an OAuth 2.0 client application registered with Mattermost. The application's client secret will be blanked out.

-
Permissions
-

Must be authenticated.

-
Authorizations:
bearerAuth
path Parameters
app_id
required
string

Application client id

-

Responses

200

App retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
404

Resource not found

-
501

Feature is disabled

-
get /oauth/apps/{app_id}/info
http://your-mattermost-url.com/api/v4/oauth/apps/{app_id}/info
https://your-mattermost-url.com/api/v4/oauth/apps/{app_id}/info

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "client_secret": "string",
  • "name": "string",
  • "description": "string",
  • "icon_url": "string",
  • "callback_urls":
    [
    ],
  • "homepage": "string",
  • "is_trusted": true,
  • "create_at": 0,
  • "update_at": 0
}

Get authorized OAuth apps

Get a page of OAuth 2.0 client applications authorized to access a user's account.

-
Permissions
-

Must be authenticated as the user or have edit_other_users permission.

-
Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

-
query Parameters
page
integer
Default: 0

The page to select.

-
per_page
integer
Default: 60

The number of apps per page.

-

Responses

200

OAuthApp list retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
501

Feature is disabled

-
get /users/{user_id}/oauth/apps/authorized
http://your-mattermost-url.com/api/v4/users/{user_id}/oauth/apps/authorized
https://your-mattermost-url.com/api/v4/users/{user_id}/oauth/apps/authorized

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

SAML

Endpoints for configuring and interacting with SAML.

-

Get metadata

Get SAML metadata from the server. SAML must be configured properly.

-
Permissions
-

No permission required.

-
Authorizations:
bearerAuth

Responses

200

SAML metadata retrieval successful

-
501

Feature is disabled

-
get /saml/metadata
http://your-mattermost-url.com/api/v4/saml/metadata
https://your-mattermost-url.com/api/v4/saml/metadata

Response samples

Content type
application/json
Copy
 Expand all Collapse all
"string"

Upload IDP certificate

Upload the IDP certificate to be used with your SAML configuration. The server will pick a hard-coded filename for the IdpCertificateFile setting in your config.json.

-
Permissions
-

Must have manage_system permission.

-
Authorizations:
bearerAuth
Request Body schema: multipart/form-data
certificate
required
string <binary>

The IDP certificate file

-

Responses

200

SAML certificate upload successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
501

Feature is disabled

-
post /saml/certificate/idp
http://your-mattermost-url.com/api/v4/saml/certificate/idp
https://your-mattermost-url.com/api/v4/saml/certificate/idp

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Remove IDP certificate

Delete the current IDP certificate being used with your SAML configuration. This will also disable SAML on your system as this certificate is required for SAML.

-
Permissions
-

Must have manage_system permission.

-
Authorizations:
bearerAuth

Responses

200

SAML certificate delete successful

-
401

No access token provided

-
403

Do not have appropriate permissions

-
501

Feature is disabled

-
delete /saml/certificate/idp
http://your-mattermost-url.com/api/v4/saml/certificate/idp
https://your-mattermost-url.com/api/v4/saml/certificate/idp

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Upload public certificate

Upload the public certificate to be used for encryption with your SAML configuration. The server will pick a hard-coded filename for the PublicCertificateFile setting in your config.json.

-
Permissions
-

Must have manage_system permission.

-
Authorizations:
bearerAuth
Request Body schema: multipart/form-data
certificate
required
string <binary>

The public certificate file

-

Responses

200

SAML certificate upload successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
501

Feature is disabled

-
post /saml/certificate/public
http://your-mattermost-url.com/api/v4/saml/certificate/public
https://your-mattermost-url.com/api/v4/saml/certificate/public

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Remove public certificate

Delete the current public certificate being used with your SAML configuration. This will also disable encryption for SAML on your system as this certificate is required for that.

-
Permissions
-

Must have manage_system permission.

-
Authorizations:
bearerAuth

Responses

200

SAML certificate delete successful

-
401

No access token provided

-
403

Do not have appropriate permissions

-
501

Feature is disabled

-
delete /saml/certificate/public
http://your-mattermost-url.com/api/v4/saml/certificate/public
https://your-mattermost-url.com/api/v4/saml/certificate/public

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Upload private key

Upload the private key to be used for encryption with your SAML configuration. The server will pick a hard-coded filename for the PrivateKeyFile setting in your config.json.

-
Permissions
-

Must have manage_system permission.

-
Authorizations:
bearerAuth
Request Body schema: multipart/form-data
certificate
required
string <binary>

The private key file

-

Responses

200

SAML certificate upload successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
501

Feature is disabled

-
post /saml/certificate/private
http://your-mattermost-url.com/api/v4/saml/certificate/private
https://your-mattermost-url.com/api/v4/saml/certificate/private

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Remove private key

Delete the current private key being used with your SAML configuration. This will also disable encryption for SAML on your system as this key is required for that.

-
Permissions
-

Must have manage_system permission.

-
Authorizations:
bearerAuth

Responses

200

SAML certificate delete successful

-
401

No access token provided

-
403

Do not have appropriate permissions

-
501

Feature is disabled

-
delete /saml/certificate/private
http://your-mattermost-url.com/api/v4/saml/certificate/private
https://your-mattermost-url.com/api/v4/saml/certificate/private

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Get certificate status

Get the status of the uploaded certificates and keys in use by your SAML configuration.

-
Permissions
-

Must have manage_system permission.

-
Authorizations:
bearerAuth

Responses

200

SAML certificate status retrieval successful

-
403

Do not have appropriate permissions

-
501

Feature is disabled

-
get /saml/certificate/status
http://your-mattermost-url.com/api/v4/saml/certificate/status
https://your-mattermost-url.com/api/v4/saml/certificate/status

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "idp_certificate_file": true,
  • "public_certificate_file": true,
  • "private_key_file": true
}

LDAP

Endpoints for configuring and interacting with LDAP.

-

Sync with LDAP

Synchronize any user attribute changes in the configured AD/LDAP server with Mattermost.

-
Permissions
-

Must have manage_system permission.

-
Authorizations:
bearerAuth

Responses

200

LDAP sync successful

-
501

Feature is disabled

-
post /ldap/sync
http://your-mattermost-url.com/api/v4/ldap/sync
https://your-mattermost-url.com/api/v4/ldap/sync

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Test LDAP configuration

Test the current AD/LDAP configuration to see if the AD/LDAP server can be contacted successfully.

-
Permissions
-

Must have manage_system permission.

-
Authorizations:
bearerAuth

Responses

200

LDAP test successful

-
500

Something went wrong with the server

-
501

Feature is disabled

-
post /ldap/test
http://your-mattermost-url.com/api/v4/ldap/test
https://your-mattermost-url.com/api/v4/ldap/test

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

groups

Endpoints related to LDAP groups.

-

Get groups

Retrieve a list of all groups not associated to a particular channel or team.

-

not_associated_to_team OR not_associated_to_channel is required.

-

If you use not_associated_to_team, you must be a team admin for that particular team (permission to manage that team).

-

If you use not_associated_to_channel, you must be a channel admin for that particular channel (permission to manage that channel).

-

Minimum server version: 5.11

-
Authorizations:
bearerAuth
query Parameters
page
integer
Default: 0

The page to select.

-
per_page
integer
Default: 60

The number of groups per page.

-
q
string

String to pattern match the name and display_name field. Will return all groups whose name and display_name field match any of the text.

-
include_member_count
boolean

Boolean which adds the member_count attribute to each group JSON object

-
not_associated_to_team
required
string

Team GUID which is used to return all the groups not associated to this team

-
not_associated_to_channel
required
string

Group GUID which is used to return all the groups not associated to this channel

-

Responses

200

Group list retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
501

Feature is disabled

-
get /groups
http://your-mattermost-url.com/api/v4/groups
https://your-mattermost-url.com/api/v4/groups

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Get a group

Get group from the provided group id string

-
Permissions
-

Must have manage_system permission.

-

Minimum server version: 5.11

-
Authorizations:
bearerAuth
path Parameters
group_id
required
string

Group GUID

-

Responses

200

Group retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
501

Feature is disabled

-
get /groups/{group_id}
http://your-mattermost-url.com/api/v4/groups/{group_id}
https://your-mattermost-url.com/api/v4/groups/{group_id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "name": "string",
  • "display_name": "string",
  • "description": "string",
  • "source": "string",
  • "remote_id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "has_syncables": true
}

Patch a group

Partially update a group by providing only the fields you want to update. Omitted fields will not be updated. The fields that can be updated are defined in the request body, all other provided fields will be ignored.

-
Permissions
-

Must have manage_system permission.

-

Minimum server version: 5.11

-
Authorizations:
bearerAuth
path Parameters
group_id
required
string

Group GUID

-
Request Body schema: application/json

Group object that is to be updated

-
name
string
display_name
string
description
string

Responses

200

Group patch successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
501

Feature is disabled

-
put /groups/{group_id}/patch
http://your-mattermost-url.com/api/v4/groups/{group_id}/patch
https://your-mattermost-url.com/api/v4/groups/{group_id}/patch

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "name": "string",
  • "display_name": "string",
  • "description": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "name": "string",
  • "display_name": "string",
  • "description": "string",
  • "source": "string",
  • "remote_id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "has_syncables": true
}

Link a team to a group

Link a team to a group

-
Permissions
-

Must have manage_team permission.

-

Minimum server version: 5.11

-
Authorizations:
bearerAuth
path Parameters
group_id
required
string

Group GUID

-
team_id
required
string

Team GUID

-

Responses

201

Team successfully linked to group

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
501

Feature is disabled

-
post /groups/{group_id}/teams/{team_id}/link
http://your-mattermost-url.com/api/v4/groups/{group_id}/teams/{team_id}/link
https://your-mattermost-url.com/api/v4/groups/{group_id}/teams/{team_id}/link

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "team_id": "string",
  • "group_id": "string",
  • "auto_add": true,
  • "create_at": 0,
  • "delete_at": 0,
  • "update_at": 0
}

Delete a link from a team to a group

Delete a link from a team to a group

-
Permissions
-

Must have manage_team permission.

-

Minimum server version: 5.11

-
Authorizations:
bearerAuth
path Parameters
group_id
required
string

Group GUID

-
team_id
required
string

Team GUID

-

Responses

200

Successfully deleted link between team and group

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
501

Feature is disabled

-
delete /groups/{group_id}/teams/{team_id}/link
http://your-mattermost-url.com/api/v4/groups/{group_id}/teams/{team_id}/link
https://your-mattermost-url.com/api/v4/groups/{group_id}/teams/{team_id}/link

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Link a channel to a group

Link a channel to a group

-
Permissions
-

If the channel is private, you must have manage_private_channel_members permission. -Otherwise, you must have the manage_public_channel_members permission.

-

Minimum server version: 5.11

-
Authorizations:
bearerAuth
path Parameters
group_id
required
string

Group GUID

-
channel_id
required
string

Channel GUID

-

Responses

201

Channel successfully linked to group

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
501

Feature is disabled

-
post /groups/{group_id}/channels/{channel_id}/link
http://your-mattermost-url.com/api/v4/groups/{group_id}/channels/{channel_id}/link
https://your-mattermost-url.com/api/v4/groups/{group_id}/channels/{channel_id}/link

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "channel_id": "string",
  • "group_id": "string",
  • "auto_add": true,
  • "create_at": 0,
  • "delete_at": 0,
  • "update_at": 0
}

Delete a link from a channel to a group

Delete a link from a channel to a group

-
Permissions
-

If the channel is private, you must have manage_private_channel_members permission. -Otherwise, you must have the manage_public_channel_members permission.

-

Minimum server version: 5.11

-
Authorizations:
bearerAuth
path Parameters
group_id
required
string

Group GUID

-
channel_id
required
string

Channel GUID

-

Responses

200

Successfully deleted link between channel and group

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
501

Feature is disabled

-
delete /groups/{group_id}/channels/{channel_id}/link
http://your-mattermost-url.com/api/v4/groups/{group_id}/channels/{channel_id}/link
https://your-mattermost-url.com/api/v4/groups/{group_id}/channels/{channel_id}/link

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Get GroupSyncable from Team ID

Get the GroupSyncable object with group_id and team_id from params

-
Permissions
-

Must have manage_system permission.

-

Minimum server version: 5.11

-
Authorizations:
bearerAuth
path Parameters
group_id
required
string

Group GUID

-
team_id
required
string

Team GUID

-

Responses

200

GroupSyncable object retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
500

Something went wrong with the server

-
501

Feature is disabled

-
get /groups/{group_id}/teams/{team_id}
http://your-mattermost-url.com/api/v4/groups/{group_id}/teams/{team_id}
https://your-mattermost-url.com/api/v4/groups/{group_id}/teams/{team_id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "team_id": "string",
  • "group_id": "string",
  • "auto_add": true,
  • "create_at": 0,
  • "delete_at": 0,
  • "update_at": 0
}

Get GroupSyncable from channel ID

Get the GroupSyncable object with group_id and channel_id from params

-
Permissions
-

Must have manage_system permission.

-

Minimum server version: 5.11

-
Authorizations:
bearerAuth
path Parameters
group_id
required
string

Group GUID

-
channel_id
required
string

Channel GUID

-

Responses

200

GroupSyncable object retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
500

Something went wrong with the server

-
501

Feature is disabled

-
get /groups/{group_id}/channels/{channel_id}
http://your-mattermost-url.com/api/v4/groups/{group_id}/channels/{channel_id}
https://your-mattermost-url.com/api/v4/groups/{group_id}/channels/{channel_id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "channel_id": "string",
  • "group_id": "string",
  • "auto_add": true,
  • "create_at": 0,
  • "delete_at": 0,
  • "update_at": 0
}

Get group teams

Retrieve the list of teams associated to the group

-
Permissions
-

Must have manage_system permission.

-

Minimum server version: 5.11

-
Authorizations:
bearerAuth
path Parameters
group_id
required
string

Group GUID

-

Responses

200

Teams list retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
500

Something went wrong with the server

-
501

Feature is disabled

-
get /groups/{group_id}/teams
http://your-mattermost-url.com/api/v4/groups/{group_id}/teams
https://your-mattermost-url.com/api/v4/groups/{group_id}/teams

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Get group channels

Retrieve the list of channels associated to the group

-
Permissions
-

Must have manage_system permission.

-

Minimum server version: 5.11

-
Authorizations:
bearerAuth
path Parameters
group_id
required
string

Group GUID

-

Responses

200

Channel list retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
500

Something went wrong with the server

-
501

Feature is disabled

-
get /groups/{group_id}/channels
http://your-mattermost-url.com/api/v4/groups/{group_id}/channels
https://your-mattermost-url.com/api/v4/groups/{group_id}/channels

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Patch a GroupSyncable associated to Team

Partially update a GroupSyncable by providing only the fields you want to update. Omitted fields will not be updated. The fields that can be updated are defined in the request body, all other provided fields will be ignored.

-
Permissions
-

Must have manage_system permission.

-

Minimum server version: 5.11

-
Authorizations:
bearerAuth
path Parameters
group_id
required
string

Group GUID

-
team_id
required
string

Team GUID

-
Request Body schema: application/json

GroupSyncable object that is to be updated

-
auto_add
boolean

Responses

200

GroupSyncable patch successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
501

Feature is disabled

-
put /groups/{group_id}/teams/{team_id}/patch
http://your-mattermost-url.com/api/v4/groups/{group_id}/teams/{team_id}/patch
https://your-mattermost-url.com/api/v4/groups/{group_id}/teams/{team_id}/patch

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "auto_add": true
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "team_id": "string",
  • "group_id": "string",
  • "auto_add": true,
  • "create_at": 0,
  • "delete_at": 0,
  • "update_at": 0
}

Patch a GroupSyncable associated to Channel

Partially update a GroupSyncable by providing only the fields you want to update. Omitted fields will not be updated. The fields that can be updated are defined in the request body, all other provided fields will be ignored.

-
Permissions
-

Must have manage_system permission.

-

Minimum server version: 5.11

-
Authorizations:
bearerAuth
path Parameters
group_id
required
string

Group GUID

-
channel_id
required
string

Channel GUID

-
Request Body schema: application/json

GroupSyncable object that is to be updated

-
auto_add
boolean

Responses

200

GroupSyncable patch successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
501

Feature is disabled

-
put /groups/{group_id}/channels/{channel_id}/patch
http://your-mattermost-url.com/api/v4/groups/{group_id}/channels/{channel_id}/patch
https://your-mattermost-url.com/api/v4/groups/{group_id}/channels/{channel_id}/patch

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "auto_add": true
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "channel_id": "string",
  • "group_id": "string",
  • "auto_add": true,
  • "create_at": 0,
  • "delete_at": 0,
  • "update_at": 0
}

Get group users

Retrieve the list of users associated with a given group.

-
Permissions
-

Must have manage_system permission.

-

Minimum server version: 5.11

-
Authorizations:
bearerAuth
path Parameters
group_id
required
string

Group GUID

-
query Parameters
page
integer
Default: 0

The page to select.

-
per_page
integer
Default: 60

The number of groups per page.

-

Responses

200

User list retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
500

Something went wrong with the server

-
501

Feature is disabled

-
get /groups/{group_id}/members
http://your-mattermost-url.com/api/v4/groups/{group_id}/members
https://your-mattermost-url.com/api/v4/groups/{group_id}/members

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "members":
    [
    ],
  • "total_member_count": 0
}

Get channel groups

Retrieve the list of groups associated with a given channel.

-
Permissions
-

Must have manage_system permission.

-

Minimum server version: 5.11

-
Authorizations:
bearerAuth
path Parameters
channel_id
required
string

Channel GUID

-
query Parameters
page
integer
Default: 0

The page to select.

-
per_page
integer
Default: 60

The number of groups per page.

-

Responses

200

Group list retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
500

Something went wrong with the server

-
501

Feature is disabled

-
get /channels/{channel_id}/groups
http://your-mattermost-url.com/api/v4/channels/{channel_id}/groups
https://your-mattermost-url.com/api/v4/channels/{channel_id}/groups

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Get team groups

Retrieve the list of groups associated with a given team.

-
Permissions
-

Must have manage_system permission.

-

Minimum server version: 5.11

-
Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

-
query Parameters
page
integer
Default: 0

The page to select.

-
per_page
integer
Default: 60

The number of groups per page.

-

Responses

200

Group list retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
500

Something went wrong with the server

-
501

Feature is disabled

-
get /teams/{team_id}/groups
http://your-mattermost-url.com/api/v4/teams/{team_id}/groups
https://your-mattermost-url.com/api/v4/teams/{team_id}/groups

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

compliance

Endpoints for creating, getting and downloading compliance reports.

-

Create report

Create and save a compliance report.

-
Permissions
-

Must have manage_system permission.

-
Authorizations:
bearerAuth

Responses

201

Compliance report creation successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
501

Feature is disabled

-
post /compliance/reports
http://your-mattermost-url.com/api/v4/compliance/reports
https://your-mattermost-url.com/api/v4/compliance/reports

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "create_at": 0,
  • "user_id": "string",
  • "status": "string",
  • "count": 0,
  • "desc": "string",
  • "type": "string",
  • "start_at": 0,
  • "end_at": 0,
  • "keywords": "string",
  • "emails": "string"
}

Get reports

Get a list of compliance reports previously created by page, selected with page and per_page query parameters.

-
Permissions
-

Must have manage_system permission.

-
Authorizations:
bearerAuth
query Parameters
page
integer
Default: 0

The page to select.

-
per_page
integer
Default: 60

The number of reports per page.

-

Responses

200

Compliance reports retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
501

Feature is disabled

-
get /compliance/reports
http://your-mattermost-url.com/api/v4/compliance/reports
https://your-mattermost-url.com/api/v4/compliance/reports

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Get a report

Get a compliance reports previously created.

-
Permissions
-

Must have manage_system permission.

-
Authorizations:
bearerAuth
path Parameters
report_id
required
string

Compliance report GUID

-

Responses

200

Compliance report retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
501

Feature is disabled

-
get /compliance/reports/{report_id}
http://your-mattermost-url.com/api/v4/compliance/reports/{report_id}
https://your-mattermost-url.com/api/v4/compliance/reports/{report_id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "create_at": 0,
  • "user_id": "string",
  • "status": "string",
  • "count": 0,
  • "desc": "string",
  • "type": "string",
  • "start_at": 0,
  • "end_at": 0,
  • "keywords": "string",
  • "emails": "string"
}

Download a report

Download the full contents of a report as a file.

-
Permissions
-

Must have manage_system permission.

-
Authorizations:
bearerAuth
path Parameters
report_id
required
string

Compliance report GUID

-

Responses

200

The compliance report file

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
501

Feature is disabled

-
get /compliance/reports/{report_id}/download
http://your-mattermost-url.com/api/v4/compliance/reports/{report_id}/download
https://your-mattermost-url.com/api/v4/compliance/reports/{report_id}/download

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

cluster

Endpoints for configuring and interacting with high availability clusters.

-

Get cluster status

Get a set of information for each node in the cluster, useful for checking the status and health of each node.

-
Permissions
-

Must have manage_system permission.

-
Authorizations:
bearerAuth

Responses

200

Cluster status retrieval successful

-
403

Do not have appropriate permissions

-
get /cluster/status
http://your-mattermost-url.com/api/v4/cluster/status
https://your-mattermost-url.com/api/v4/cluster/status

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

elasticsearch

Endpoints for configuring and interacting with Elasticsearch.

-

Test Elasticsearch configuration

Test the current Elasticsearch configuration to see if the Elasticsearch server can be contacted successfully. -Optionally provide a configuration in the request body to test. If no valid configuration is present in the -request body the current server configuration will be tested.

-

Minimum server version: 4.1

-
Permissions
-

Must have manage_system permission.

-
Authorizations:
bearerAuth

Responses

200

Elasticsearch test successful

-
400

Invalid or missing parameters in URL or request body

-
500

Something went wrong with the server

-
501

Feature is disabled

-
post /elasticsearch/test
http://your-mattermost-url.com/api/v4/elasticsearch/test
https://your-mattermost-url.com/api/v4/elasticsearch/test

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Purge all Elasticsearch indexes

Deletes all Elasticsearch indexes and their contents. After calling this endpoint, it is -necessary to schedule a new Elasticsearch indexing job to repopulate the indexes. -Minimum server version: 4.1

-
Permissions
-

Must have manage_system permission.

-
Authorizations:
bearerAuth

Responses

200

Indexes purged successfully.

-
500

Something went wrong with the server

-
501

Feature is disabled

-
post /elasticsearch/purge_indexes
http://your-mattermost-url.com/api/v4/elasticsearch/purge_indexes
https://your-mattermost-url.com/api/v4/elasticsearch/purge_indexes

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

dataretention

Endpoint for getting data retention policy settings.

-

Get the data retention policy details.

Gets the current data retention policy details from the server, including what data should be purged and the cutoff times for each data type that should be purged. -Minimum server version: 4.3

-
Permissions
-

Requires an active session but no other permissions.

-
Authorizations:
bearerAuth

Responses

200

Data retention policy details retrieved successfully.

-
500

Something went wrong with the server

-
501

Feature is disabled

-
get /data_retention/policy
http://your-mattermost-url.com/api/v4/data_retention/policy
https://your-mattermost-url.com/api/v4/data_retention/policy

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "message_deletion_enabled": true,
  • "file_deletion_enabled": true,
  • "message_retention_cutoff": 0,
  • "file_retention_cutoff": 0
}

jobs

Endpoints related to various background jobs that can be run by the server or separately by job servers.

-

Get the jobs.

Get a page of jobs. Use the query parameters to modify the behaviour of this endpoint. -Minimum server version: 4.1

-
Permissions
-

Must have manage_jobs permission.

-
Authorizations:
bearerAuth
query Parameters
page
integer
Default: 0

The page to select.

-
per_page
integer
Default: 60

The number of jobs per page.

-

Responses

200

Job list retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
get /jobs
http://your-mattermost-url.com/api/v4/jobs
https://your-mattermost-url.com/api/v4/jobs

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Create a new job.

Create a new job. -Minimum server version: 4.1

-
Permissions
-

Must have manage_jobs permission.

-
Authorizations:
bearerAuth
Request Body schema: application/json

Job object to be created

-
type
required
string

The type of job to create

-
data
object

An object containing any additional data required for this job type

-

Responses

201

Job creation successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
post /jobs
http://your-mattermost-url.com/api/v4/jobs
https://your-mattermost-url.com/api/v4/jobs

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "type": "string",
  • "data": { }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "type": "string",
  • "create_at": 0,
  • "start_at": 0,
  • "last_activity_at": 0,
  • "status": "string",
  • "progress": 0,
  • "data": { }
}

Get a job.

Gets a single job. -Minimum server version: 4.1

-
Permissions
-

Must have manage_jobs permission.

-
Authorizations:
bearerAuth
path Parameters
job_id
required
string

Job GUID

-

Responses

200

Job retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
get /jobs/{job_id}
http://your-mattermost-url.com/api/v4/jobs/{job_id}
https://your-mattermost-url.com/api/v4/jobs/{job_id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "type": "string",
  • "create_at": 0,
  • "start_at": 0,
  • "last_activity_at": 0,
  • "status": "string",
  • "progress": 0,
  • "data": { }
}

Cancel a job.

Cancel a job. -Minimum server version: 4.1

-
Permissions
-

Must have manage_jobs permission.

-
Authorizations:
bearerAuth
path Parameters
job_id
required
string

Job GUID

-

Responses

200

Job canceled successfully

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
post /jobs/{job_id}/cancel
http://your-mattermost-url.com/api/v4/jobs/{job_id}/cancel
https://your-mattermost-url.com/api/v4/jobs/{job_id}/cancel

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Get the jobs of the given type.

Get a page of jobs of the given type. Use the query parameters to modify the behaviour of this endpoint. -Minimum server version: 4.1

-
Permissions
-

Must have manage_jobs permission.

-
Authorizations:
bearerAuth
path Parameters
type
required
string

Job type

-
query Parameters
page
integer
Default: 0

The page to select.

-
per_page
integer
Default: 60

The number of jobs per page.

-

Responses

200

Job list retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
get /jobs/type/{type}
http://your-mattermost-url.com/api/v4/jobs/type/{type}
https://your-mattermost-url.com/api/v4/jobs/type/{type}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

plugins

Endpoints related to uploading and managing plugins.

-

Upload plugin

Upload a plugin that is contained within a compressed .tar.gz file. Plugins and plugin uploads must be enabled in the server's config settings.

-
Permissions
-

Must have manage_system permission.

-

Minimum server version: 4.4

-
Authorizations:
bearerAuth
Request Body schema: multipart/form-data
plugin
required
string <binary>

The plugin image to be uploaded

-
force
string

Set to 'true' to overwrite a previously installed plugin with the same ID, if any

-

Responses

201

Plugin upload successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
413

Content too large

-
501

Feature is disabled

-
post /plugins
http://your-mattermost-url.com/api/v4/plugins
https://your-mattermost-url.com/api/v4/plugins

Request samples

Copy
import (
-  "bytes"
-  "io/ioutil"
-  "log"
-
-  "github.com/mattermost/mattermost-server/model"
-)
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-tarData, err := ioutil.ReadFile("plugin.tar.gz")
-if err != nil {
-  log.Fatal("error while reading file")
-}
-
-// Not forced
-manifest, resp := Client.UploadPlugin(bytes.NewReader(tarData))
-
-// Forced
-manifest, resp := Client.UploadPluginForced(bytes.NewReader(tarData))
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Get plugins

Get a list of inactive and a list of active plugin manifests. Plugins must be enabled in the server's config settings.

-
Permissions
-

Must have manage_system permission.

-

Minimum server version: 4.4

-
Authorizations:
bearerAuth

Responses

200

Plugins retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
501

Feature is disabled

-
get /plugins
http://your-mattermost-url.com/api/v4/plugins
https://your-mattermost-url.com/api/v4/plugins

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-pluginsResp, resp := Client.GetPlugins()
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "active":
    [
    ],
  • "inactive":
    [
    ]
}

Install plugin from url

Supply a URL to a plugin compressed in a .tar.gz file. Plugins must be enabled in the server's config settings.

-
Permissions
-

Must have manage_system permission.

-

Minimum server version: 5.14

-
Authorizations:
bearerAuth
query Parameters
plugin_download_url
required
string

URL used to download the plugin

-
force
string

Set to 'true' to overwrite a previously installed plugin with the same ID, if any

-

Responses

201

Plugin install successful

-
400

Invalid or missing parameters in URL or request body

-
403

Do not have appropriate permissions

-
501

Feature is disabled

-
post /plugins/install_from_url
http://your-mattermost-url.com/api/v4/plugins/install_from_url
https://your-mattermost-url.com/api/v4/plugins/install_from_url

Request samples

Copy
import (
-  "github.com/mattermost/mattermost-server/model"
-)
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-url := "https://mysite.com/my-plugin.tar.gz"
-
-// Not forced
-manifest, resp := Client.InstallPluginFromUrl(url, false)
-
-// Forced
-manifest, resp := Client.InstallPluginFromUrl(url, true)
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Remove plugin

Remove the plugin with the provided ID from the server. All plugin files are deleted. Plugins must be enabled in the server's config settings.

-
Permissions
-

Must have manage_system permission.

-

Minimum server version: 4.4

-
Authorizations:
bearerAuth
path Parameters
plugin_id
required
string

Responses

200

Plugin removed successfully

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
501

Feature is disabled

-
delete /plugins/{plugin_id}
http://your-mattermost-url.com/api/v4/plugins/{plugin_id}
https://your-mattermost-url.com/api/v4/plugins/{plugin_id}

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-pluginID := "com.mattermost.demo-plugin"
-
-ok, resp = Client.RemovePlugin(pluginID)
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Enable plugin

Enable a previously uploaded plugin. Plugins must be enabled in the server's config settings.

-
Permissions
-

Must have manage_system permission.

-

Minimum server version: 4.4

-
Authorizations:
bearerAuth
path Parameters
plugin_id
required
string

Responses

200

Plugin enabled successfully

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
501

Feature is disabled

-
post /plugins/{plugin_id}/enable
http://your-mattermost-url.com/api/v4/plugins/{plugin_id}/enable
https://your-mattermost-url.com/api/v4/plugins/{plugin_id}/enable

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-pluginID := "com.mattermost.demo-plugin"
-
-ok, resp = Client.EnablePlugin(pluginID)
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Disable plugin

Disable a previously enabled plugin. Plugins must be enabled in the server's config settings.

-
Permissions
-

Must have manage_system permission.

-

Minimum server version: 4.4

-
Authorizations:
bearerAuth
path Parameters
plugin_id
required
string

Responses

200

Plugin disabled successfully

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
501

Feature is disabled

-
post /plugins/{plugin_id}/disable
http://your-mattermost-url.com/api/v4/plugins/{plugin_id}/disable
https://your-mattermost-url.com/api/v4/plugins/{plugin_id}/disable

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-pluginID := "com.mattermost.demo-plugin"
-
-ok, resp = Client.DisablePlugin(pluginID)
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Get webapp plugins

Get a list of web app plugins installed and activated on the server.

-
Permissions
-

No permissions required.

-

Minimum server version: 4.4

-
Authorizations:
bearerAuth

Responses

200

Plugin deactivated successfully

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
501

Feature is disabled

-
get /plugins/webapp
http://your-mattermost-url.com/api/v4/plugins/webapp
https://your-mattermost-url.com/api/v4/plugins/webapp

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-
-manifests, resp := Client.GetWebappPlugins()
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Installs a marketplace plugin

Installs a plugin listed in the marketplace server.

-
Permissions
-

Must have manage_system permission.

-

Minimum server version: 5.16

-
Authorizations:
bearerAuth
Request Body schema: application/json

The metadata identifying the plugin to install.

-
id
required
string

The ID of the plugin to install.

-
version
required
string

The version of the plugin to install.

-

Responses

200

Plugin installed successfully

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
501

Feature is disabled

-
post /plugins/marketplace
http://your-mattermost-url.com/api/v4/plugins/marketplace
https://your-mattermost-url.com/api/v4/plugins/marketplace

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "version": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

Gets all the marketplace plugins

Gets all plugins from the marketplace server, merging data from locally installed plugins as well as prepackaged plugins shipped with the server.

-
Permissions
-

Must have manage_system permission.

-

Minimum server version: 5.16

-
Authorizations:
bearerAuth
query Parameters
page
integer

Page number to be fetched. (not yet implemented)

-
per_page
integer

Number of item per page. (not yet implemented)

-
filter
string

Set to filter plugins by ID, name, or description.

-
server_version
string

Set to filter minimum plugin server version. (not yet implemented)

-
local_only
boolean

Set true to only retrieve local plugins.

-

Responses

200

Plugins retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
501

Feature is disabled

-
get /plugins/marketplace
http://your-mattermost-url.com/api/v4/plugins/marketplace
https://your-mattermost-url.com/api/v4/plugins/marketplace

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-filter := &model.MarketplacePluginFilter{
-  Page: 1,
-  PerPage: 10,
-  Filter: "antivirus",
-  ServerVersion: "0.1.2",
-  LocalOnly: true,
-}
-
-ok, resp = Client.GetMarketplacePlugins(filter)
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status_code": 0,
  • "id": "string",
  • "message": "string",
  • "request_id": "string"
}

roles

Endpoints for creating, getting and updating roles.

-

Get a role

Get a role from the provided role id.

-
Permissions
-

Requires an active session but no other permissions.

-

Minimum server version: 4.9

-
Authorizations:
bearerAuth
path Parameters
role_id
required
string

Role GUID

-

Responses

200

Role retrieval successful

-
401

No access token provided

-
404

Resource not found

-
get /roles/{role_id}
http://your-mattermost-url.com/api/v4/roles/{role_id}
https://your-mattermost-url.com/api/v4/roles/{role_id}

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-role, resp := Client.GetRole(<ROLEID>, "")
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "name": "string",
  • "display_name": "string",
  • "description": "string",
  • "permissions":
    [
    ],
  • "scheme_managed": true
}

Get a role

Get a role from the provided role name.

-
Permissions
-

Requires an active session but no other permissions.

-

Minimum server version: 4.9

-
Authorizations:
bearerAuth
path Parameters
role_name
required
string

Role Name

-

Responses

200

Role retrieval successful

-
401

No access token provided

-
404

Resource not found

-
get /roles/name/{role_name}
http://your-mattermost-url.com/api/v4/roles/name/{role_name}
https://your-mattermost-url.com/api/v4/roles/name/{role_name}

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-role, resp := Client.GetRoleByName(<ROLENAME>, "")
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "name": "string",
  • "display_name": "string",
  • "description": "string",
  • "permissions":
    [
    ],
  • "scheme_managed": true
}

Patch a role

Partially update a role by providing only the fields you want to update. Omitted fields will not be updated. The fields that can be updated are defined in the request body, all other provided fields will be ignored.

-
Permissions
-

manage_system permission is required.

-

Minimum server version: 4.9

-
Authorizations:
bearerAuth
path Parameters
role_id
required
string

Role GUID

-
Request Body schema: application/json

Role object to be updated

-
permissions
Array of strings

The permissions the role should grant.

-

Responses

200

Role patch successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
put /roles/{role_id}/patch
http://your-mattermost-url.com/api/v4/roles/{role_id}/patch
https://your-mattermost-url.com/api/v4/roles/{role_id}/patch

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "permissions":
    [
    ]
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "name": "string",
  • "display_name": "string",
  • "description": "string",
  • "permissions":
    [
    ],
  • "scheme_managed": true
}

Get a list of roles by name

Get a list of roles from their names.

-
Permissions
-

Requires an active session but no other permissions.

-

Minimum server version: 4.9

-
Authorizations:
bearerAuth
Request Body schema: application/json

List of role names

-
Array
string

Responses

200

Role list retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
404

Resource not found

-
post /roles/names
http://your-mattermost-url.com/api/v4/roles/names
https://your-mattermost-url.com/api/v4/roles/names

Request samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • "string"
]

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

schemes

Endpoints for creating, getting and updating and deleting schemes.

-

Get the schemes.

Get a page of schemes. Use the query parameters to modify the behaviour of this endpoint.

-
Permissions
-

Must have manage_system permission.

-

Minimum server version: 5.0

-
Authorizations:
bearerAuth
query Parameters
scope
string
Default: ""

Limit the results returned to the provided scope, either team or channel.

-
page
integer
Default: 0

The page to select.

-
per_page
integer
Default: 60

The number of schemes per page.

-

Responses

200

Scheme list retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
get /schemes
http://your-mattermost-url.com/api/v4/schemes
https://your-mattermost-url.com/api/v4/schemes

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Create a scheme

Create a new scheme.

-
Permissions
-

Must have manage_system permission.

-

Minimum server version: 5.0

-
Authorizations:
bearerAuth
Request Body schema: application/json

Scheme object to create

-
name
required
string

The name of the scheme

-
description
string

The description of the scheme

-
scope
required
string

The scope of the scheme ("team" or "channel")

-

Responses

201

Scheme creation successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
501

Feature is disabled

-
post /schemes
http://your-mattermost-url.com/api/v4/schemes
https://your-mattermost-url.com/api/v4/schemes

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "name": "string",
  • "description": "string",
  • "scope": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "scope": "string",
  • "default_team_admin_role": "string",
  • "default_team_user_role": "string",
  • "default_channel_admin_role": "string",
  • "default_channel_user_role": "string"
}

Get a scheme

Get a scheme from the provided scheme id.

-
Permissions
-

Must have manage_system permission.

-

Minimum server version: 5.0

-
Authorizations:
bearerAuth
path Parameters
scheme_id
required
string

Scheme GUID

-

Responses

200

Scheme retrieval successful

-
401

No access token provided

-
404

Resource not found

-
501

Feature is disabled

-
get /schemes/{scheme_id}
http://your-mattermost-url.com/api/v4/schemes/{scheme_id}
https://your-mattermost-url.com/api/v4/schemes/{scheme_id}

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-scheme, resp := Client.GetScheme(<SCHEMEID>, "")
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "scope": "string",
  • "default_team_admin_role": "string",
  • "default_team_user_role": "string",
  • "default_channel_admin_role": "string",
  • "default_channel_user_role": "string"
}

Delete a scheme

Soft deletes a scheme, by marking the scheme as deleted in the database.

-
Permissions
-

Must have manage_system permission.

-

Minimum server version: 5.0

-
Authorizations:
bearerAuth
path Parameters
scheme_id
required
string

ID of the scheme to delete

-

Responses

200

Scheme deletion successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
501

Feature is disabled

-
delete /schemes/{scheme_id}
http://your-mattermost-url.com/api/v4/schemes/{scheme_id}
https://your-mattermost-url.com/api/v4/schemes/{scheme_id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Patch a scheme

Partially update a scheme by providing only the fields you want to update. Omitted fields will not be updated. The fields that can be updated are defined in the request body, all other provided fields will be ignored.

-
Permissions
-

manage_system permission is required.

-

Minimum server version: 5.0

-
Authorizations:
bearerAuth
path Parameters
scheme_id
required
string

Scheme GUID

-
Request Body schema: application/json

Scheme object to be updated

-
name
string

The human readable name of the scheme

-
description
string

The description of the scheme

-

Responses

200

Scheme patch successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
501

Feature is disabled

-
put /schemes/{scheme_id}/patch
http://your-mattermost-url.com/api/v4/schemes/{scheme_id}/patch
https://your-mattermost-url.com/api/v4/schemes/{scheme_id}/patch

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "name": "string",
  • "description": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "scope": "string",
  • "default_team_admin_role": "string",
  • "default_team_user_role": "string",
  • "default_channel_admin_role": "string",
  • "default_channel_user_role": "string"
}

Get a page of teams which use this scheme.

Get a page of teams which use this scheme. The provided Scheme ID should be for a Team-scoped Scheme. -Use the query parameters to modify the behaviour of this endpoint.

-
Permissions
-

manage_system permission is required.

-

Minimum server version: 5.0

-
Authorizations:
bearerAuth
path Parameters
scheme_id
required
string

Scheme GUID

-
query Parameters
page
integer
Default: 0

The page to select.

-
per_page
integer
Default: 60

The number of teams per page.

-

Responses

200

Team list retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
get /schemes/{scheme_id}/teams
http://your-mattermost-url.com/api/v4/schemes/{scheme_id}/teams
https://your-mattermost-url.com/api/v4/schemes/{scheme_id}/teams

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Get a page of channels which use this scheme.

Get a page of channels which use this scheme. The provided Scheme ID should be for a Channel-scoped Scheme. -Use the query parameters to modify the behaviour of this endpoint.

-
Permissions
-

manage_system permission is required.

-

Minimum server version: 5.0

-
Authorizations:
bearerAuth
path Parameters
scheme_id
required
string

Scheme GUID

-
query Parameters
page
integer
Default: 0

The page to select.

-
per_page
integer
Default: 60

The number of channels per page.

-

Responses

200

Channel list retrieval successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
404

Resource not found

-
get /schemes/{scheme_id}/channels
http://your-mattermost-url.com/api/v4/schemes/{scheme_id}/channels
https://your-mattermost-url.com/api/v4/schemes/{scheme_id}/channels

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

integration_actions

Endpoints for interactive actions for use by integrations.

-

Open a dialog

Open an interactive dialog using a trigger ID provided by a slash command, or some other action payload. See https://docs.mattermost.com/developer/interactive-dialogs.html for more information on interactive dialogs. -Minimum server version: 5.6

-
Authorizations:
bearerAuth
Request Body schema: application/json

Metadata for the dialog to be opened

-
trigger_id
required
string

Trigger ID provided by other action

-
url
required
string

The URL to send the submitted dialog payload to

-
dialog
required
object

Post object to create

-

Responses

200

Dialog open successful

-
400

Invalid or missing parameters in URL or request body

-
post /actions/dialogs/open
http://your-mattermost-url.com/api/v4/actions/dialogs/open
https://your-mattermost-url.com/api/v4/actions/dialogs/open

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "trigger_id": "string",
  • "url": "string",
  • "dialog":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Submit a dialog

Endpoint used by the Mattermost clients to submit a dialog. See https://docs.mattermost.com/developer/interactive-dialogs.html for more information on interactive dialogs. -Minimum server version: 5.6

-
Authorizations:
bearerAuth
Request Body schema: application/json

Dialog submission data

-
url
required
string

The URL to send the submitted dialog payload to

-
channel_id
required
string

Channel ID the user submitted the dialog from

-
team_id
required
string

Team ID the user submitted the dialog from

-
submission
required
object

String map where keys are element names and values are the element input values

-
callback_id
string

Callback ID sent when the dialog was opened

-
state
string

State sent when the dialog was opened

-
cancelled
boolean

Set to true if the dialog was cancelled

-

Responses

200

Dialog submission successful

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
post /actions/dialogs/submit
http://your-mattermost-url.com/api/v4/actions/dialogs/submit
https://your-mattermost-url.com/api/v4/actions/dialogs/submit

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "url": "string",
  • "channel_id": "string",
  • "team_id": "string",
  • "submission": { },
  • "callback_id": "string",
  • "state": "string",
  • "cancelled": true
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

terms of service

Endpoints for getting and updating custom terms of service.

-

Records user action when they accept or decline custom terms of service

Records user action when they accept or decline custom terms of service. Records the action in audit table. -Updates user's last accepted terms of service ID if they accepted it.

-

Minimum server version: 5.4

-
Permissions
-

Must be logged in as the user being acted on.

-
Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

-
Request Body schema: application/json

terms of service details

-
serviceTermsId
required
string

terms of service ID on which the user is acting on

-
accepted
required
string

true or false, indicates whether the user accepted or rejected the terms of service.

-

Responses

200

Terms of service action recorded successfully

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
403

Do not have appropriate permissions

-
post /users/{user_id}/terms_of_service
http://your-mattermost-url.com/api/v4/users/{user_id}/terms_of_service
https://your-mattermost-url.com/api/v4/users/{user_id}/terms_of_service

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "serviceTermsId": "string",
  • "accepted": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "string"
}

Fetches user's latest terms of service action if the latest action was for acceptance.

Will be deprecated in v6.0 -Fetches user's latest terms of service action if the latest action was for acceptance.

-

Minimum server version: 5.6

-
Permissions
-

Must be logged in as the user being acted on.

-
Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

-

Responses

200

User's accepted terms of service action

-
400

Invalid or missing parameters in URL or request body

-
401

No access token provided

-
404

User hasn't performed an action or the latest action was a rejection.

-
get /users/{user_id}/terms_of_service
http://your-mattermost-url.com/api/v4/users/{user_id}/terms_of_service
https://your-mattermost-url.com/api/v4/users/{user_id}/terms_of_service

Request samples

Copy
import "github.com/mattermost/mattermost-server/model"
-
-Client := model.NewAPIv4Client("https://your-mattermost-url.com")
-Client.Login("email@domain.com", "Password1")
-
-userID := "adWv1qPZmHdtxk7Lmqh6RtxWxS"
-
-userTermsOfService, resp := Client.GetUserTermsOfService(userID, "")
-

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "user_id": "string",
  • "terms_of_service_id": "string",
  • "create_at": 0
}
- - - -