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.

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.

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.

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

Official Drivers

• Mattermost JavaScript Driver
• Mattermost Golang Driver

Community-built Drivers

• PHP Driver - built by @gnello and @prixone
• Python Driver - built by @Vaelor

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

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.

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
}

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.

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

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 using the standard API authentification methods (by a cookie or with an explicit Authorization header) 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
• thread_updated
• thread_follow_changed
• thread_read_changed

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 data field is used to add any additional data along with the request. The server supports binary websocket messages as well in case the client has such a requirement.

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.

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.