Mattermost API Reference (4.0.0)

Download OpenAPI specification:Download

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. 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. 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. 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. Set your server's log level back to ERROR. Use the error logs to help track down any remaining uses of API v3.

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. Collection endpoints now generally return lists and include paging as part of the query string.
  3. User ID is now included in most user endpoints. This allows admins to modify other users through v4 endpoints.

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.

Header Description
X-Ratelimit-Limit The maximum number of requests you can make per second.
X-Ratelimit-Remaining The number of requests remaining in the current window.
X-Ratelimit-Reset The remaining UTC epoch seconds before the rate limit resets.

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

HTTP/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:
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:
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:
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:
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:
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:
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:
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:

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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:

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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:

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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:

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:

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:
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:
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:
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:

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:
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:

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:
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:

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:
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:
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:

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:
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:
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:

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:
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:
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:
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:
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:

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:

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:

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:
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:

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:
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:
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:
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:
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:
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:
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:
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:
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:

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:
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:

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:
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:

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:
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:

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:

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:

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:

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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:

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:
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:
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:
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:

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:

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:

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:

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:
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:
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:
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:
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:
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:
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:

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:
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:
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:
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:
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:

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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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
}