Mattermost Web Service API

This provides a basic overview of the Mattermost Web Service API. Drivers interfacing with this API are available in different languages. Current documentation focuses on the transport layer for the API and functional documentation will be developed next.

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

Schema

All API access is done through yourdomain.com/api/v1/, with all data being sent and received as JSON.

Authentication

The majority of the Mattermost API involves interacting with teams. Therefore, most API methods require authentication as a user. There are two ways to authenticate into a Mattermost system.

Session Token

Make an HTTP POST to yourdomain.com/api/v1/users/login with a JSON body indicating the name of the team, the user's email and password.

curl -i -d '{"name":"exampleteam","email":"someone@nowhere.com","password":"thisisabadpassword"}' http://localhost:8065/api/v1/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 Authentication header on your future API requests with the Bearer method.

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

That's it! You should now be able to access the API as the user you logged in as.

OAuth2

Coming soon...

Client Errors

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

{
    "message": "", // the reason for the error
    "detailed_error": "", // some extra details about the error
    "request_id": "", // the ID of the request
    "status_code": 0 // the HTTP status code
}

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