Mattermost API Reference (4.0.0)

Download OpenAPI specification:Download

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

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.

Login to Mattermost server

Permissions

No permission required

Authorizations:
Request Body schema: application/json

User authentication object

id
string
login_id
string
token
string
device_id
string
ldap_only
boolean
password
string

The password used for email authentication.

Responses

201

User login successful

400

Invalid or missing parameters in URL or request body

403

Do not have appropriate permissions

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

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "login_id": "string",
  • "token": "string",
  • "device_id": "string",
  • "ldap_only": true,
  • "password": "string"
}

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
}

Logout from the Mattermost server

Permissions

An active session is required

Authorizations:

Responses

201

User logout successful

400

Invalid or missing parameters in URL or request body

403

Do not have appropriate permissions

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

Response samples

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

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.

in_group
string

The ID of the group to get users for. Must have manage_system permission.

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.

active
boolean

Whether or not to list only users that are active. This option cannot be used along with the inactive option.

inactive
boolean

Whether or not to list only users that are deactivated. This option cannot be used along with the active option.

role
string

Returns users that have this role.

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

roles
string

Comma separated string used to filter users based on any of the specified system roles

Example: ?roles=system_admin,system_user will return users that are either system admins or system users

Minimum server version: 5.26

channel_roles
string

Comma separated string used to filter users based on any of the specified channel roles, can only be used in conjunction with in_channel

Example: ?in_channel=4eb6axxw7fg3je5iyasnfudc5y&channel_roles=channel_user will return users that are only channel users and not admins or guests

Minimum server version: 5.26

team_roles
string

Comma separated string used to filter users based on any of the specified team roles, can only be used in conjunction with in_team

Example: ?in_team=4eb6axxw7fg3je5iyasnfudc5y&team_roles=team_user will return users that are only team users and not admins or guests

Minimum server version: 5.26

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/v5/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
[
  • {
    }
]

Permanent delete all users

Permanently deletes all users and all their related information, including posts.

Minimum server version: 5.26.0

Local mode only: This endpoint is only available through local mode.

Authorizations:

Responses

200

Delete request was successful

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

Request samples

Copy
import (
    "net"
    "net/http"

    "github.com/mattermost/mattermost-server/v5/model"
)

tr := &http.Transport{
    Dial: func(network, addr string) (net.Conn, error) {
        return net.Dial("unix", socketPath)
    },
}

Client := model.NewAPIv4Client("http://_")
Client.HttpClient = &http.Client{Transport: tr}

ok, resp := Client.PermanentDeleteAllUsers()

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

in_group_id
string

If provided, only search users in this group. Must have manage_system permission.

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",
  • "in_group_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/v5/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 user IDs of known users

Get the list of user IDs of users with any direct relationship with a user. That means any user sharing any channel, including direct and group channels.

Permissions

Must be authenticated.

Minimum server version: 5.23

Authorizations:

Responses

200

Known users' IDs retrieval successful

401

No access token provided

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

Request samples

Copy
import "github.com/mattermost/mattermost-server/v5/model"

Client := model.NewAPIv4Client("https://your-mattermost-url.com")
Client.Login("email@domain.com", "Password1")

userIds, resp := Client.GetKnownUsers()

Response samples

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

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/v5/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 total count of users in the system matching the specified filters

Get a count of users in the system matching the specified filters.

Minimum server version: 5.26

Permissions

Must have manage_system permission.

Authorizations:
query Parameters
in_team
string

The ID of the team to get user stats for.

in_channel
string

The ID of the channel to get user stats for.

include_deleted
boolean

If deleted accounts should be included in the count.

include_bots
boolean

If bot accounts should be included in the count.

roles
string

Comma separated string used to filter users based on any of the specified system roles

Example: ?roles=system_admin,system_user will include users that are either system admins or system users

channel_roles
string

Comma separated string used to filter users based on any of the specified channel roles, can only be used in conjunction with in_channel

Example: ?in_channel=4eb6axxw7fg3je5iyasnfudc5y&channel_roles=channel_user will include users that are only channel users and not admins or guests

team_roles
string

Comma separated string used to filter users based on any of the specified team roles, can only be used in conjunction with in_team

Example: ?in_team=4eb6axxw7fg3je5iyasnfudc5y&team_roles=team_user will include users that are only team users and not admins or guests

Responses

200

Filtered 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/filtered
http://your-mattermost-url.com/api/v4/users/stats/filtered
https://your-mattermost-url.com/api/v4/users/stats/filtered

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. This can also be "me" which will point to the current user.

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/v5/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/v5/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/v5/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/v5/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/v5/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/v5/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/v5/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/v5/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/v5/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/v5/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"
}

Convert a user into a bot

Convert a user into a bot.

Minimum server version: 5.26

Permissions

Must have manage_system permission.

Authorizations:
path Parameters
user_id
required
string

User GUID

Responses

200

User successfully converted

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 /users/{user_id}/convert_to_bot
http://your-mattermost-url.com/api/v4/users/{user_id}/convert_to_bot
https://your-mattermost-url.com/api/v4/users/{user_id}/convert_to_bot

Request samples

Copy
import "github.com/mattermost/mattermost-server/v5/model"

Client := model.NewAPIv4Client("https://your-mattermost-url.com")

userId := "BbaYBYDV5IDOZFiJGBSzkw1k5u"

bot, resp := Client.ConvertUserToBot(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/v5/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/v5/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/v5/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/v5/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 by ID

Verify the email used by a user without a token.

Minimum server version: 5.24

Permissions

Must have manage_system permission.

Authorizations:
path Parameters
user_id
required
string

User GUID

Responses

200

User email verification successful

400

Invalid or missing parameters in URL or request body

401

No access token provided

404

Resource not found

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

Request samples

Copy
import "github.com/mattermost/mattermost-server/v5/model"

Client := model.NewAPIv4Client("https://your-mattermost-url.com")
Client.Login("email@domain.com", "Password1")

userID := "BbaYBYDV5IDOZFiJGBSzkw1k5u

user, resp := Client.VerifyUserEmailWithoutToken(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
}

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/v5/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/v5/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/v5/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/v5/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/v5/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"
}

Publish a user typing websocket event.

Notify users in the given channel via websocket that the given user is typing. Minimum server version: 5.26

Permissions

Must have manage_system permission to publish for any user other than oneself.

Authorizations:
path Parameters
user_id
required
string

User GUID

Request Body schema: application/json
channel_id
required
string

The id of the channel to which to direct the typing event.

parent_id
string

The optional id of the root post of the thread to which the user is replying. If unset, the typing event is directed at the entire channel.

Responses

200

User typing websocket event accepted for publishing.

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}/typing
http://your-mattermost-url.com/api/v4/users/{user_id}/typing
https://your-mattermost-url.com/api/v4/users/{user_id}/typing

Request samples

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

Response samples

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

Convert a bot into a user

Convert a bot into a user.

Minimum server version: 5.26

Permissions

Must have manage_system permission.

Authorizations:
path Parameters
bot_user_id
required
string

Bot user ID

query Parameters
set_system_admin
boolean
Default: false

Whether to give the user the system admin role.

Request Body schema: application/json

Data to be used in the user creation

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

Responses

200

Bot successfully converted

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 /bots/{bot_user_id}/convert_to_user
http://your-mattermost-url.com/api/v4/bots/{bot_user_id}/convert_to_user
https://your-mattermost-url.com/api/v4/bots/{bot_user_id}/convert_to_user

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "email": "string",
  • "username": "string",
  • "password": "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
{
  • "status": "string"
}

bots

Endpoints for creating, getting and updating bot users.

Convert a user into a bot

Convert a user into a bot.

Minimum server version: 5.26

Permissions

Must have manage_system permission.

Authorizations:
path Parameters
user_id
required
string

User GUID

Responses

200

User successfully converted

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 /users/{user_id}/convert_to_bot
http://your-mattermost-url.com/api/v4/users/{user_id}/convert_to_bot
https://your-mattermost-url.com/api/v4/users/{user_id}/convert_to_bot

Request samples

Copy
import "github.com/mattermost/mattermost-server/v5/model"

Client := model.NewAPIv4Client("https://your-mattermost-url.com")

userId := "BbaYBYDV5IDOZFiJGBSzkw1k5u"

bot, resp := Client.ConvertUserToBot(userId)

Response samples

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

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

Request samples

Copy
require 'vendor/autoload.php';

use \Gnello\Mattermost\Driver;

$container = new \Pimple\Container([
    "driver" => [
        "url" => "https://your-mattermost-url.com",
        "login_id" => "email@domain.com",
        "password" => "Password1",
    ]
]);

$driver = new Driver($container);
$driver->authenticate();

$resp = $driver->getBotModel()->getBots([
    "page" => 0,
    "per_page" => 60,
    "include_deleted" => true,
    "only_orphaned" => true,
]);

if ($resp->getStatusCode() == 200) {
    $bots = json_decode($resp->getBody());
}

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}

Request samples

Copy
require 'vendor/autoload.php';

use \Gnello\Mattermost\Driver;

$container = new \Pimple\Container([
    "driver" => [
        "url" => "https://your-mattermost-url.com",
        "login_id" => "email@domain.com",
        "password" => "Password1",
    ]
]);

$driver = new Driver($container);
$driver->authenticate();

$botUserID = "4xp9fdt77pncbef59f4k1qe83o";

$resp = $driver->getBotModel()->getBot($botUserID, [
    "include_deleted" => true,
]);

if ($resp->getStatusCode() == 200) {
    $bot = json_decode($resp->getBody());
}

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

Request samples

Copy
require 'vendor/autoload.php';

use \Gnello\Mattermost\Driver;

$container = new \Pimple\Container([
    "driver" => [
        "url" => "https://your-mattermost-url.com",
        "login_id" => "email@domain.com",
        "password" => "Password1",
    ]
]);

$driver = new Driver($container);
$driver->authenticate();

$botUserID = "4xp9fdt77pncbef59f4k1qe83o";

$resp = $driver->getBotModel()->disableBot($botUserID);

if ($resp->getStatusCode() == 200) {
    $disabledBot = json_decode($resp->getBody());
}

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

Request samples

Copy
require 'vendor/autoload.php';

use \Gnello\Mattermost\Driver;

$container = new \Pimple\Container([
    "driver" => [
        "url" => "https://your-mattermost-url.com",
        "login_id" => "email@domain.com",
        "password" => "Password1",
    ]
]);

$driver = new Driver($container);
$driver->authenticate();

$botUserID = "4xp9fdt77pncbef59f4k1qe83o";

$resp = $driver->getBotModel()->enableBot($botUserID);

if ($resp->getStatusCode() == 200) {
    $enabledBot = json_decode($resp->getBody());
}

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}

Request samples

Copy
require 'vendor/autoload.php';

use \Gnello\Mattermost\Driver;

$container = new \Pimple\Container([
    "driver" => [
        "url" => "https://your-mattermost-url.com",
        "login_id" => "email@domain.com",
        "password" => "Password1",
    ]
]);

$driver = new Driver($container);
$driver->authenticate();

$botUserID = "4xp9fdt77pncbef59f4k1qe83o";
$userID = "adWv1qPZmHdtxk7Lmqh6RtxWxS";

$resp = $driver->getBotModel()->assignBotToUser($botUserID, $userID);

if ($resp->getStatusCode() == 200) {
    $assignedBot = json_decode($resp->getBody());
}

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/v5/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/v5/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/v5/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"
}

Convert a bot into a user

Convert a bot into a user.

Minimum server version: 5.26

Permissions

Must have manage_system permission.

Authorizations:
path Parameters
bot_user_id
required
string

Bot user ID

query Parameters
set_system_admin
boolean
Default: false

Whether to give the user the system admin role.

Request Body schema: application/json

Data to be used in the user creation

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

Responses

200

Bot successfully converted

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 /bots/{bot_user_id}/convert_to_user
http://your-mattermost-url.com/api/v4/bots/{bot_user_id}/convert_to_user
https://your-mattermost-url.com/api/v4/bots/{bot_user_id}/convert_to_user

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "email": "string",
  • "username": "string",
  • "password": "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
{
  • "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/v5/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/v5/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/v5/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
}

Update teams's privacy

Updates team's privacy allowing changing a team from Public (open) to Private (invitation only) and back.

Minimum server version: 5.24

Permissions

manage_team permission for the team of the team.

Authorizations:
path Parameters
team_id
required
string

Team GUID

Request Body schema: application/json
privacy
required
string

Team privacy setting: 'O' for a public (open) team, 'I' for a private (invitation only) team

Responses

200

Team 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 /teams/{team_id}/privacy
http://your-mattermost-url.com/api/v4/teams/{team_id}/privacy
https://your-mattermost-url.com/api/v4/teams/{team_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
{
  • "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
}

Restore a team

Restore a team that was previously soft deleted.

Minimum server version: 5.24

Permissions

Must have the manage_team permission.

Authorizations:
path Parameters
team_id
required
string

Team GUID

Responses

200

Team restore successful

401

No access token provided

403

Do not have appropriate permissions

404

Resource not found

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

Request samples

Copy
import "github.com/mattermost/mattermost-server/v5/model"
Client := model.NewAPIv4Client("https://your-mattermost-url.com")
Client.Login("email@domain.com", "Password1")
teamID := "4xp9fdt77pncbef59f4k1qe83o"
team, resp := Client.RestoreTeam(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"