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 and large 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/tree/master/api.

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.

drivers

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

Official Drivers

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.

Migrate user accounts authentication type to LDAP.

Migrates accounts from one authentication provider to another. For example, you can upgrade your authentication provider from email to LDAP. Minimum server version: 5.28

Permissions

Must have manage_system permission.

Authorizations:
bearerAuth
Request Body schema: application/json
from
required
string

The current authentication type for the matched users.

match_field
required
string

Foreign user field name to match.

force
required
boolean

Responses

Request samples

Content type
application/json
{
  • "from": "string",
  • "match_field": "string",
  • "force": true
}

Response samples

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

Migrate user accounts authentication type to SAML.

Migrates accounts from one authentication provider to another. For example, you can upgrade your authentication provider from email to SAML. Minimum server version: 5.28

Permissions

Must have manage_system permission.

Authorizations:
bearerAuth
Request Body schema: application/json
from
required
string

The current authentication type for the matched users.

matches
required
object

Users map.

auto
required
boolean

Responses

Request samples

Content type
application/json
{
  • "from": "string",
  • "matches": { },
  • "auto": true
}

Response samples

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

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 using the standard API authentication 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.

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

Request samples

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

Response samples

Content type
application/json
{
  • "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
}

Auto-Login to Mattermost server using CWS token

CWS stands for Customer Web Server which is the cloud service used to manage cloud instances.

Permissions

A Cloud license is required

Authorizations:
bearerAuth
Request Body schema: application/json

User authentication object

login_id
string
cws_token
string

Responses

Request samples

Content type
application/json
{
  • "login_id": "string",
  • "cws_token": "string"
}

Response samples

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

Logout from the Mattermost server

Permissions

An active session is required

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "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 for creating email/username accounts on an open server. Auth Token is required for other authentication types such as LDAP or SAML.

Authorizations:
bearerAuth
query Parameters
t
string

Token id from an email invitation

iid
string

Token id from an invitation link

Request Body schema: application/json

User object to be created

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

Service-specific authentication data, such as email address.

auth_service
string

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

password
string

The password used for email authentication.

locale
string
props
object
object (UserNotifyProps)

Responses

Request samples

Content type
application/json
{
  • "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
{
  • "id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "username": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "nickname": "string",
  • "email": "string",
  • "email_verified": true,
  • "auth_service": "string",
  • "roles": "string",
  • "locale": "string",
  • "notify_props": {
    },
  • "props": { },
  • "last_password_update": 0,
  • "last_picture_update": 0,
  • "failed_attempts": 0,
  • "mfa_active": true,
  • "timezone": {
    },
  • "terms_of_service_id": "string",
  • "terms_of_service_create_at": 0
}

Get users

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

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

Permissions

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

Authorizations:
bearerAuth
query Parameters
page
integer
Default: 0

The page to select.

per_page
integer
Default: 60

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

in_team
string

The ID of the team to get users for.

not_in_team
string

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

in_channel
string

The ID of the channel to get users for.

not_in_channel
string

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

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. Note that when "last_activity_at" is specified, an additional "last_activity_at" field will be returned in the response packet. 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

in_group

Can be "", "display_name". When left blank, sorting is done by username. display_name will sort alphabetically by user's display name. Minimum server version: 7.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

Request samples

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/mattermost/mattermost/server/public/model"
)

func main() {
	client := model.NewAPIv4Client("http://localhost:8065")
	client.SetToken(os.Getenv("MM_TOKEN"))

	const perPage = 100
	var page int
	for {
		users, _, err := client.GetUsers(context.TODO(), page, perPage, "")
		if err != nil {
			log.Printf("error fetching users: %v", err)
			return
		}

		for _, u := range users {
			fmt.Printf("%s\n", u.Username)
		}

		if len(users) < perPage {
			break
		}

		page++
	}
}

Response samples

Content type
application/json
[
  • {
    }
]

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

Responses

Get users by ids

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

Permissions

Requires an active session but no other permissions.

Authorizations:
bearerAuth
query Parameters
since
integer

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

Minimum server version: 5.14

Request Body schema: application/json

List of user ids

Array
string

Responses

Request samples

Content type
application/json
[
  • "string"
]

Response samples

Content type
application/json
[
  • {
    }
]

Get users by group channels ids

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

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

Permissions

Requires an active session but no other permissions.

Minimum server version: 5.14

Authorizations:
bearerAuth
Request Body schema: application/json

List of group channel ids

Array
string

Responses

Request samples

Content type
application/json
[
  • "string"
]

Response samples

Content type
application/json
{
  • "<CHANNEL_ID>": [
    ]
}

Get users by usernames

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

Permissions

Requires an active session but no other permissions.

Authorizations:
bearerAuth
Request Body schema: application/json

List of usernames

Array
string

Responses

Request samples

Content type
application/json
[
  • "string"
]

Response samples

Content type
application/json
[
  • {
    }
]

Search users

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

Permissions

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

Authorizations:
bearerAuth
Request Body schema: application/json

Search criteria

term
required
string

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

team_id
string

If provided, only search users on this team

not_in_team_id
string

If provided, only search users not on this team

in_channel_id
string

If provided, only search users in this channel

not_in_channel_id
string

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

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

Request samples

Content type
application/json
{
  • "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
[
  • {
    }
]

Autocomplete users

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

Permissions

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

Authorizations:
bearerAuth
query Parameters
team_id
string

Team ID

channel_id
string

Channel ID

name
required
string

Username, nickname first name or last name

limit
integer
Default: 100

The maximum number of users to return in each subresult

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

Responses

Response samples

Content type
application/json
{
  • "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:
bearerAuth

Responses

Response samples

Content type
application/json
[ ]

Get total count of users in the system

Get a total count of users in the system.

Permissions

Must be authenticated.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "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:
bearerAuth
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

Response samples

Content type
application/json
{
  • "total_users_count": 0
}

Get a user

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

Permissions

Requires an active session but no other permissions.

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID. This can also be "me" which will point to the current user.

Responses

Response samples

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

Update a user

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

Permissions

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

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

Request Body schema: application/json

User object that is to be updated

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

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "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.

As of server version 5.28, optionally use the permanent=true query parameter to permanently delete the user for compliance reasons. To use this feature ServiceSettings.EnableAPIUserDeletion must be set to true in the server's configuration.

Permissions

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

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Patch a user

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

Permissions

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

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

Request Body schema: application/json

User object that is to be updated

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

Responses

Request samples

Content type
application/json
{
  • "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
{
  • "id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "username": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "nickname": "string",
  • "email": "string",
  • "email_verified": true,
  • "auth_service": "string",
  • "roles": "string",
  • "locale": "string",
  • "notify_props": {
    },
  • "props": { },
  • "last_password_update": 0,
  • "last_picture_update": 0,
  • "failed_attempts": 0,
  • "mfa_active": true,
  • "timezone": {
    },
  • "terms_of_service_id": "string",
  • "terms_of_service_create_at": 0
}

Update a user's roles

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

Permissions

Must have the manage_roles permission.

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

Request Body schema: application/json

Space-delimited system roles to assign to the user

roles
required
string

Responses

Request samples

Content type
application/json
{
  • "roles": "string"
}

Response samples

Content type
application/json
{
  • "status": "string"
}

Update user active status

Update user active or inactive status.

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

Permissions

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

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

Request Body schema: application/json

Use true to set the user active, false for inactive

active
required
boolean

Responses

Request samples

Content type
application/json
{
  • "active": true
}

Response samples

Content type
application/json
{
  • "status": "string"
}

Get user's profile image

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

Permissions

Must be logged in.

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

query Parameters
_
number

Not used by the server. Clients can pass in the last picture update time of the user to potentially take advantage of caching

Responses

Response samples

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

Set user's profile image

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

Permissions

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

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

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

The image to be uploaded

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Delete user's profile image

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

Permissions

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

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Return user's default (generated) profile image

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

Permissions

Must be logged in. Minimum server version: 5.5

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

Responses

Response samples

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

Get a user by username

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

Permissions

Requires an active session but no other permissions.

Authorizations:
bearerAuth
path Parameters
username
required
string

Username

Responses

Response samples

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

Reset password

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

Permissions

No permissions required.

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

The recovery code

new_password
required
string

The new password for the user

Responses

Request samples

Content type
application/json
{
  • "code": "string",
  • "new_password": "string"
}

Response samples

Content type
application/json
{
  • "status": "string"
}

Update a user's MFA

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

Permissions

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

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

Request Body schema: application/json
activate
required
boolean

Use true to activate, false to deactivate

code
string

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

Responses

Request samples

Content type
application/json
{
  • "activate": true,
  • "code": "string"
}

Response samples

Content type
application/json
{
  • "status": "string"
}

Generate MFA secret

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

Permissions

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

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

Responses

Response samples

Content type
application/json
{
  • "secret": "string",
  • "qr_code": "string"
}

Demote a user to a guest

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

Minimum server version: 5.16

Permissions

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

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Promote a guest to user

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

Minimum server version: 5.16

Permissions

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

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

Responses

Response samples

Content type
application/json
{
  • "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:
bearerAuth
path Parameters
user_id
required
string

User GUID

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Check MFA

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

Permissions

No permission required.

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

The email or username used to login

Responses

Request samples

Content type
application/json
{
  • "login_id": "string"
}

Response samples

Content type
application/json
{
  • "mfa_required": true
}

Update a user's password

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

Permissions

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

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

Request Body schema: application/json
current_password
string

The current password for the user

new_password
required
string

The new password for the user

Responses

Request samples

Content type
application/json
{
  • "current_password": "string",
  • "new_password": "string"
}

Response samples

Content type
application/json
{
  • "status": "string"
}

Send password reset email

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

Permissions

No permissions required.

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

The email of the user

Responses

Request samples

Content type
application/json
{
  • "email": "string"
}

Response samples

Content type
application/json
{
  • "status": "string"
}

Get a user by email

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

Permissions

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

Authorizations:
bearerAuth
path Parameters
email
required
string

User Email

Responses

Response samples

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

Get user's sessions

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

Permissions

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

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Revoke a user session

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

Permissions

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

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

Request Body schema: application/json
session_id
required
string

The session GUID to revoke.

Responses

Request samples

Content type
application/json
{
  • "session_id": "string"
}

Response samples

Content type
application/json
{
  • "status": "string"
}

Revoke all active sessions for a user

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

Permissions

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

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Attach mobile device

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

Permissions

Must be authenticated.

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

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

Responses

Request samples

Content type
application/json
{
  • "device_id": "string"
}

Response samples

Content type
application/json
{
  • "status": "string"
}

Get user's audits

Get a list of audit by providing the user GUID.

Permissions

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

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

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:
bearerAuth
path Parameters
user_id
required
string

User GUID

Responses

Response samples

Content type
application/json
{
  • "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:
bearerAuth
Request Body schema: application/json
token
required
string

The token given to validate the email

Responses

Request samples

Content type
application/json
{
  • "token": "string"
}

Response samples

Content type
application/json
{
  • "status": "string"
}

Send verification email

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

Permissions

No permissions required.

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

Email of a user

Responses

Request samples

Content type
application/json
{
  • "email": "string"
}

Response samples

Content type
application/json
{
  • "status": "string"
}

Switch login method

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

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

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

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

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

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

Permissions

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

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

The service the user currently uses to login

new_service
required
string

The service the user will use to login

email
string

The email of the user

password
string

The password used with the current service

mfa_code
string

The MFA code of the current service

ldap_id
string

The LDAP/AD id of the user

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "follow_link": "string"
}

Create a user access token

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

Minimum server version: 4.1

Permissions

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

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

Request Body schema: application/json
description
required
string

A description of the token usage

Responses

Request samples

Content type
application/json
{
  • "description": "string"
}

Response samples

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

Get user access tokens

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

Minimum server version: 4.1

Permissions

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

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

query Parameters
page
integer
Default: 0

The page to select.

per_page
integer
Default: 60

The number of tokens per page.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get user access tokens

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

Minimum server version: 4.7

Permissions

Must have manage_system permission.

Authorizations:
bearerAuth
query Parameters
page
integer
Default: 0

The page to select.

per_page
integer
Default: 60

The number of tokens per page.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Revoke a user access token

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

Minimum server version: 4.1

Permissions

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

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

The user access token GUID to revoke

Responses

Request samples

Content type
application/json
{
  • "token_id": "string"
}

Response samples

Content type
application/json
{
  • "status": "string"
}

Get a user access token

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

Minimum server version: 4.1

Permissions

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

Authorizations:
bearerAuth
path Parameters
token_id
required
string

User access token GUID

Responses

Response samples

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

Disable personal access token

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

Minimum server version: 4.4

Permissions

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

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

The personal access token GUID to disable

Responses

Request samples

Content type
application/json
{
  • "token_id": "string"
}

Response samples

Content type
application/json
{
  • "status": "string"
}

Enable personal access token

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

Minimum server version: 4.4

Permissions

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

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

The personal access token GUID to enable

Responses

Request samples

Content type
application/json
{
  • "token_id": "string"
}

Response samples

Content type
application/json
{
  • "status": "string"
}

Search tokens

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

Minimum server version: 4.7

Permissions

Must have manage_system permission.

Authorizations:
bearerAuth
Request Body schema: application/json

Search criteria

term
required
string

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

Responses

Request samples

Content type
application/json
{
  • "term": "string"
}

Response samples

Content type
application/json
[
  • {
    }
]

Update a user's authentication method

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

Minimum server version: 4.6

Permissions

Must have the edit_other_users permission.

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

Request Body schema: application/json
auth_data
required
string

Service-specific authentication data

auth_service
required
string

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

Responses

Request samples

Content type
application/json
{
  • "auth_data": "string",
  • "auth_service": "string"
}

Response samples

Content type
application/json
{
  • "auth_data": "string",
  • "auth_service": "string"
}

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

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

Minimum server version: 5.4

Permissions

Must be logged in as the user being acted on.

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

Request Body schema: application/json

terms of service details

serviceTermsId
required
string

terms of service ID on which the user is acting on

accepted
required
string

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

Responses

Request samples

Content type
application/json
{
  • "serviceTermsId": "string",
  • "accepted": "string"
}

Response samples

Content type
application/json
{
  • "status": "string"
}

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

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

Minimum server version: 5.6

Permissions

Must be logged in as the user being acted on.

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

Responses

Response samples

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

Revoke all sessions from all users.

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

Minimum server version: 5.14

Permissions

Must have manage_system permission.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "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:
bearerAuth
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

Request samples

Content type
application/json
{
  • "channel_id": "string",
  • "parent_id": "string"
}

Response samples

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

Get uploads for a user

Gets all the upload sessions belonging to a user.

Minimum server version: 5.28

Permissions

Must be logged in as the user who created the upload sessions.

Authorizations:
bearerAuth
path Parameters
user_id
required
string

The ID of the user. This can also be "me" which will point to the current user.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get all channel members from all teams for a user

Get all channel members from all teams for a user.

Minimum server version: 6.2.0

Permissions

Logged in as the user, or have edit_other_users permission.

Authorizations:
bearerAuth
path Parameters
user_id
required
string

The ID of the user. This can also be "me" which will point to the current user.

query Parameters
page
integer

Page specifies which part of the results to return, by PageSize.

pageSize
integer

PageSize specifies the size of the returned chunk of results.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Migrate user accounts authentication type to LDAP.

Migrates accounts from one authentication provider to another. For example, you can upgrade your authentication provider from email to LDAP. Minimum server version: 5.28

Permissions

Must have manage_system permission.

Authorizations:
bearerAuth
Request Body schema: application/json
from
required
string

The current authentication type for the matched users.

match_field
required
string

Foreign user field name to match.

force
required
boolean

Responses

Request samples

Content type
application/json
{
  • "from": "string",
  • "match_field": "string",
  • "force": true
}

Response samples

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

Migrate user accounts authentication type to SAML.

Migrates accounts from one authentication provider to another. For example, you can upgrade your authentication provider from email to SAML. Minimum server version: 5.28

Permissions

Must have manage_system permission.

Authorizations:
bearerAuth
Request Body schema: application/json
from
required
string

The current authentication type for the matched users.

matches
required
object

Users map.

auto
required
boolean

Responses

Request samples

Content type
application/json
{
  • "from": "string",
  • "matches": { },
  • "auto": true
}

Response samples

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

Get users with invalid emails

Get users whose emails are considered invalid. It is an error to invoke this API if your team settings enable an open server.

Permissions

Requires sysconsole_read_user_management_users.

Authorizations:
bearerAuth
query Parameters
page
integer
Default: 0

The page to select.

per_page
integer
Default: 60

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

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Convert a bot into a user

Convert a bot into a user.

Minimum server version: 5.26

Permissions

Must have manage_system permission.

Authorizations:
bearerAuth
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
object (UserNotifyProps)

Responses

Request samples

Content type
application/json
{
  • "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
{
  • "status": "string"
}

Get a list of paged and sorted users for admin reporting purposes

Get a list of paged users for admin reporting purposes, based on provided parameters. Must be a system admin to invoke this API.

Permissions

Requires sysconsole_read_user_management_users.

Authorizations:
bearerAuth
query Parameters
sort_column
string
Default: "Username"

The column to sort the users by. Must be one of ("CreateAt", "Username", "FirstName", "LastName", "Nickname", "Email") or the API will return an error.

direction
string
Default: "down"

The direction in which to accept paging values from. Will return values ahead of the cursor if "up", and below the cursor if "down". Default is "down".

sort_direction
string
Default: "asc"

The sorting direction. Must be one of ("asc", "desc"). Will default to 'asc' if not specified or the input is invalid.

page_size
integer [ 1 .. 100 ]
Default: 50

The maximum number of users to return.

from_column_value
string

The value of the sorted column corresponding to the cursor to read from. Should be blank for the first page asked for.

from_id
string

The value of the user id corresponding to the cursor to read from. Should be blank for the first page asked for.

date_range
string
Default: "alltime"

The date range of the post statistics to display. Must be one of ("last30days", "previousmonth", "last6months", "alltime"). Will default to 'alltime' if the input is not valid.

role_filter
string

Filter users by their role.

team_filter
string

Filter users by a specified team ID.

has_no_team
boolean

If true, show only users that have no team. Will ignore provided "team_filter" if true.

hide_active
boolean

If true, show only users that are inactive. Cannot be used at the same time as "hide_inactive"

hide_inactive
boolean

If true, show only users that are active. Cannot be used at the same time as "hide_active"

search_term
string

A filtering search term that allows filtering by Username, FirstName, LastName, Nickname or Email

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Gets the full count of users that match the filter.

Get the full count of users admin reporting purposes, based on provided parameters.

Must be a system admin to invoke this API.

Permissions

Requires sysconsole_read_user_management_users.

Authorizations:
bearerAuth
query Parameters
role_filter
string

Filter users by their role.

team_filter
string

Filter users by a specified team ID.

has_no_team
boolean

If true, show only users that have no team. Will ignore provided "team_filter" if true.

hide_active
boolean

If true, show only users that are inactive. Cannot be used at the same time as "hide_inactive"

hide_inactive
boolean

If true, show only users that are active. Cannot be used at the same time as "hide_active"

search_term
string

A filtering search term that allows filtering by Username, FirstName, LastName, Nickname or Email

Responses

Response samples

Content type
application/json
0
0

Gets the user limits for the server

Gets the user limits for the server

Permissions

Requires sysconsole_read_user_management_users.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

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:
bearerAuth
path Parameters
user_id
required
string

User GUID

Responses

Response samples

Content type
application/json
{
  • "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:
bearerAuth
Request Body schema: application/json

Bot to be created

username
required
string
display_name
string
description
string

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "display_name": "string",
  • "description": "string"
}

Response samples

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

Get bots

Get a page of a list of bots.

Permissions

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

Authorizations:
bearerAuth
query Parameters
page
integer
Default: 0

The page to select.

per_page
integer
Default: 60

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

include_deleted
boolean

If deleted bots should be returned.

only_orphaned
boolean

When true, only orphaned bots will be returned. A bot is considered orphaned if its owner has been deactivated.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Patch a bot

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

Permissions

Must have manage_bots permission. Minimum server version: 5.10

Authorizations:
bearerAuth
path Parameters
bot_user_id
required
string

Bot user ID

Request Body schema: application/json

Bot to be created

username
required
string
display_name
string
description
string

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "display_name": "string",
  • "description": "string"
}

Response samples

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

Get a bot

Get a bot specified by its bot id.

Permissions

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

Authorizations:
bearerAuth
path Parameters
bot_user_id
required
string

Bot user ID

query Parameters
include_deleted
boolean

If deleted bots should be returned.

Responses

Response samples

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

Disable a bot

Disable a bot.

Permissions

Must have manage_bots permission. Minimum server version: 5.10

Authorizations:
bearerAuth
path Parameters
bot_user_id
required
string

Bot user ID

Responses

Response samples

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

Enable a bot

Enable a bot.

Permissions

Must have manage_bots permission. Minimum server version: 5.10

Authorizations:
bearerAuth
path Parameters
bot_user_id
required
string

Bot user ID

Responses

Response samples

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

Assign a bot to a user

Assign a bot to a specified user.

Permissions

Must have manage_bots permission. Minimum server version: 5.10

Authorizations:
bearerAuth
path Parameters
bot_user_id
required
string

Bot user ID

user_id
required
string

The user ID to assign the bot to.

Responses

Response samples

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

Get bot's LHS icon

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

Permissions

Must be logged in. Minimum server version: 5.14

Authorizations:
bearerAuth
path Parameters
bot_user_id
required
string

Bot user ID

Responses

Response samples

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

Set bot's LHS icon image

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

Permissions

Must have manage_bots permission. Minimum server version: 5.14

Authorizations:
bearerAuth
path Parameters
bot_user_id
required
string

Bot user ID

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

SVG icon image to be uploaded

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Delete bot's LHS icon image

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

Permissions

Must have manage_bots permission. Minimum server version: 5.14

Authorizations:
bearerAuth
path Parameters
bot_user_id
required
string

Bot user ID

Responses

Response samples

Content type
application/json
{
  • "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:
bearerAuth
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
object (UserNotifyProps)

Responses

Request samples

Content type
application/json
{
  • "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
{
  • "status": "string"
}

teams

Endpoints for creating, getting and interacting with teams.

Create a team

Create a new team on the system.

Permissions

Must be authenticated and have the create_team permission.

Authorizations:
bearerAuth
Request Body schema: application/json

Team that is to be created

name
required
string

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

display_name
required
string

Non-unique UI name for the team

type
required
string

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

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "display_name": "string",
  • "type": "string"
}

Response samples

Content type
application/json
{
  • "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,
  • "policy_id": "string"
}

Get teams

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

Permissions

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

Authorizations:
bearerAuth
query Parameters
page
integer
Default: 0

The page to select.

per_page
integer
Default: 60

The number of teams per page.

include_total_count
boolean
Default: false

Appends a total count of returned teams inside the response object - ex: { "teams": [], "total_count" : 0 }.

exclude_policy_constrained
boolean
Default: false

If set to true, teams which are part of a data retention policy will be excluded. The sysconsole_read_compliance permission is required to use this parameter. Minimum server version: 5.35

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a team

Get a team on the system.

Permissions

Must be authenticated and have the view_team permission.

Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

Responses

Response samples

Content type
application/json
{
  • "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,
  • "policy_id": "string"
}

Update a team

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

Permissions

Must have the manage_team permission.

Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

Request Body schema: application/json

Team to update

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

Responses

Request samples

Content type
application/json
{
  • "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
{
  • "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,
  • "policy_id": "string"
}

Delete a team

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

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

Permissions

Must have the manage_team permission.

Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

query Parameters
permanent
boolean
Default: false

Permanently delete the team, to be used for compliance reasons only. As of server version 5.0, ServiceSettings.EnableAPITeamDeletion must be set to true in the server's configuration.

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Patch a team

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

Permissions

Must have the manage_team permission.

Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

Request Body schema: application/json

Team object that is to be updated

display_name
string
description
string
company_name
string
invite_id
string
allow_open_invite
boolean

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "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,
  • "policy_id": "string"
}

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

Request samples

Content type
application/json
{
  • "privacy": "string"
}

Response samples

Content type
application/json
{
  • "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,
  • "policy_id": "string"
}

Restore a team

Restore a team that was previously soft deleted.

Minimum server version: 5.24

Permissions

Must have the manage_team permission.

Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

Responses

Response samples

Content type
application/json
{
  • "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,
  • "policy_id": "string"
}

Get a team by name

Get a team based on provided name string

Permissions

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

Authorizations:
bearerAuth
path Parameters
name
required
string

Team Name

Responses

Response samples

Content type
application/json
{
  • "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,
  • "policy_id": "string"
}

Search teams

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

Permissions

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

Authorizations:
bearerAuth
Request Body schema: application/json

Search criteria

term
string

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

page
string

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

per_page
string

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

allow_open_invite
boolean

Filters results to teams where allow_open_invite is set to true or false, excludes group constrained channels if this filter option is passed. If this filter option is not passed then the query will remain unchanged. Minimum server version: 5.28

group_constrained
boolean

Filters results to teams where group_constrained is set to true or false, returns the union of results when used with allow_open_invite If the filter option is not passed then the query will remain unchanged. Minimum server version: 5.28

exclude_policy_constrained
boolean
Default: false

If set to true, only teams which do not have a granular retention policy assigned to them will be returned. The sysconsole_read_compliance_data_retention permission is required to use this parameter. Minimum server version: 5.35

Responses

Request samples

Content type
application/json
{
  • "term": "string",
  • "page": "string",
  • "per_page": "string",
  • "allow_open_invite": true,
  • "group_constrained": true,
  • "exclude_policy_constrained": false
}

Response samples

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

Check if team exists

Check if the team exists based on a team name.

Permissions

Must be authenticated.

Authorizations:
bearerAuth
path Parameters
name
required
string

Team Name

Responses

Response samples

Content type
application/json
{
  • "exists": true
}

Get a user's teams

Get a list of teams that a user is on.

Permissions

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

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get team members

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

Permissions

Must be authenticated and have the view_team permission.

Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

query Parameters
page
integer
Default: 0

The page to select.

per_page
integer
Default: 60

The number of users per page.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add user to team

Add user to the team by user_id.

Permissions

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

Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

Request Body schema: application/json
team_id
string
user_id
string

Responses

Request samples

Content type
application/json
{
  • "team_id": "string",
  • "user_id": "string"
}

Response samples

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

Add user to team from invite

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

Permissions

Must be authenticated.

Authorizations:
bearerAuth
query Parameters
token
required
string

Token id from the invitation

Responses

Response samples

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

Add multiple users to team

Add a number of users to the team by user_id.

Permissions

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

Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

query Parameters
graceful
boolean

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

Request Body schema: application/json
Array
team_id
string

The ID of the team this member belongs to.

user_id
string

The ID of the user this member relates to.

roles
string

The complete list of roles assigned to this team member, as a space-separated list of role names, including any roles granted implicitly through permissions schemes.

delete_at
integer

The time in milliseconds that this team member was deleted.

scheme_user
boolean

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

scheme_admin
boolean

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

explicit_roles
string

The list of roles explicitly assigned to this team member, as a space separated list of role names. This list does not include any roles granted implicitly through permissions schemes.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Get team members for a user

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

Permissions

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

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a team member

Get a team member on the system.

Permissions

Must be authenticated and have the view_team permission.

Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

user_id
required
string

User GUID

Responses

Response samples

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

Remove user from team

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

Permissions

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

Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

user_id
required
string

User GUID

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Get team members by ids

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

Permissions

Must have view_team permission for the team.

Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

Request Body schema: application/json

List of user ids

Array
string

Responses

Request samples

Content type
application/json
[
  • "string"
]

Response samples

Content type
application/json
[
  • {
    }
]

Get a team stats

Get a team stats on the system.

Permissions

Must be authenticated and have the view_team permission.

Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

Responses

Response samples

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

Regenerate the Invite ID from a Team

Regenerates the invite ID used in invite links of a team

Permissions

Must be authenticated and have the manage_team permission.

Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

Responses

Response samples

Content type
application/json
{
  • "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,
  • "policy_id": "string"
}

Get the team icon

Get the team icon of the team.

Minimum server version: 4.9

Permissions

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

Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

Responses

Response samples

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

Sets the team icon

Sets the team icon for the team.

Minimum server version: 4.9

Permissions

Must be authenticated and have the manage_team permission.

Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

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

The image to be uploaded

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Remove the team icon

Remove the team icon for the team.

Minimum server version: 4.10

Permissions

Must be authenticated and have the manage_team permission.

Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Update a team member roles

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

Permissions

Must be authenticated and have the manage_team_roles permission.

Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

user_id
required
string

User GUID

Request Body schema: application/json

Space-delimited team roles to assign to the user

roles
required
string

Responses

Request samples

Content type
application/json
{
  • "roles": "string"
}

Response samples

Content type
application/json
{
  • "status": "string"
}

Update the scheme-derived roles of a team member.

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

Minimum server version: 5.0

Permissions

Must be authenticated and have the manage_team_roles permission.

Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

user_id
required
string

User GUID

Request Body schema: application/json

Scheme properties.

scheme_admin
required
boolean
scheme_user
required
boolean

Responses

Request samples

Content type
application/json
{
  • "scheme_admin": true,
  • "scheme_user": true
}

Response samples

Content type
application/json
{
  • "status": "string"
}

Get team unreads for a user

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

Permissions

Must be logged in.

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

query Parameters
exclude_team
required
string

Optional team id to be excluded from the results

include_collapsed_threads
boolean
Default: false

Boolean to determine whether the collapsed threads should be included or not

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get unreads for a team

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

Permissions

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

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

team_id
required
string

Team GUID

Responses

Response samples

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

Invite users to the team by email

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

The number of emails that can be sent is rate limited to 20 per hour with a burst of 20 emails. If the rate limit exceeds, the error message contains details on when to retry and when the timer will be reset.

Permissions

Must have invite_user and add_user_to_team permissions for the team.

Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

Request Body schema: application/json

List of user's email

Array
string

Responses

Request samples

Content type
application/json
[
  • "string"
]

Response samples

Content type
application/json
{
  • "status": "string"
}

Invite guests to the team by email

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

The number of emails that can be sent is rate limited to 20 per hour with a burst of 20 emails. If the rate limit exceeds, the error message contains details on when to retry and when the timer will be reset.

Minimum server version: 5.16

Permissions

Must have invite_guest permission for the team.

Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

Request Body schema: application/json

Guests invite information

emails
required
Array of strings

List of emails

channels
required
Array of strings

List of channel ids

message
string

Message to include in the invite

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "status": "string"
}

Invalidate active email invitations

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

Permissions

Must have sysconsole_write_authentication permission.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Import a Team from other application

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

Permissions

Must have permission_import_team permission.

Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

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

A file to be uploaded in zip format.

filesize
required
integer

The size of the zip file to be imported.

importFrom
required
string

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

Responses

Response samples

Content type
application/json
{
  • "results": "string"
}

Get invite info for a team

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

Minimum server version: 4.0

Permissions

No authentication required.

Authorizations:
bearerAuth
path Parameters
invite_id
required
string

Invite id for a team

Responses

Response samples

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

Set a team's scheme

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

Permissions

Must have manage_system permission.

Minimum server version: 5.0

Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

Request Body schema: application/json

Scheme GUID

scheme_id
required
string

The ID of the scheme.

Responses

Request samples

Content type
application/json
{
  • "scheme_id": "string"
}

Response samples

Content type
application/json
{
  • "status": "string"
}

Team members minus group members.

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

Permissions

Must have manage_system permission.

Minimum server version: 5.14

Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

query Parameters
group_ids
required
string
Default: ""

A comma-separated list of group ids.

page
integer
Default: 0

The page to select.

per_page
integer
Default: 0

The number of users per page.

Responses

Response samples

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

Search files in a team

Search for files in a team based on file name, extention and file content (if file content extraction is enabled and supported for the files). Minimum server version: 5.34

Permissions

Must be authenticated and have the view_team permission.

Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

Request Body schema: multipart/form-data

The search terms and logic to use in the search.

terms
required
string

The search terms as inputed by the user. To search for files from a user include from:someusername, using a user's username. To search in a specific channel include in:somechannel, using the channel name (not the display name). To search for specific extensions included ext:extension.

is_or_search
required
boolean

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

time_zone_offset
integer
Default: 0

Offset from UTC of user timezone for date searches.

include_deleted_channels
boolean

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

page
integer
Default: 0

The page to select. (Only works with Elasticsearch)

per_page
integer
Default: 60

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

Responses

Response samples

Content type
application/json
{
  • "order": [
    ],
  • "file_infos": {
    },
  • "next_file_id": "string",
  • "prev_file_id": "string"
}

channels

Endpoints for creating, getting and interacting with channels.

Get a list of all channels

Permissions

manage_system

Authorizations:
bearerAuth
query Parameters
not_associated_to_group
string

A group id to exclude channels that are associated with that group via GroupChannel records. This can also be left blank with not_associated_to_group=.

page
integer
Default: 0

The page to select.

per_page
integer
Default: 0

The number of channels per page.

exclude_default_channels
boolean
Default: false

Whether to exclude default channels (ex Town Square, Off-Topic) from the results.

include_deleted
boolean
Default: false

Include channels that have been archived. This correlates to the DeleteAt flag being set in the database.

include_total_count
boolean
Default: false

Appends a total count of returned channels inside the response object - ex: { "channels": [], "total_count" : 0 }.

exclude_policy_constrained
boolean
Default: false

If set to true, channels which are part of a data retention policy will be excluded. The sysconsole_read_compliance permission is required to use this parameter. Minimum server version: 5.35

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a channel

Create a new channel.

Permissions

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

Authorizations:
bearerAuth
Request Body schema: application/json

Channel object to be created

team_id
required
string

The team ID of the team to create the channel on

name
required
string

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

display_name
required
string

The non-unique UI name for the channel

purpose
string

A short description of the purpose of the channel

header
string

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

type
required
string

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

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "team_id": "string",
  • "type": "string",
  • "display_name": "string",
  • "name": "string",
  • "header": "string",
  • "purpose": "string",
  • "last_post_at": 0,
  • "total_msg_count": 0,
  • "extra_update_at": 0,
  • "creator_id": "string"
}

Create a direct message channel

Create a new direct message channel between two users.

Permissions

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

Authorizations:
bearerAuth
Request Body schema: application/json

The two user ids to be in the direct message

Array (= 2 items)
string

Responses

Request samples

Content type
application/json
[
  • "string",
  • "string"
]

Response samples

Content type
application/json
{
  • "id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "team_id": "string",
  • "type": "string",
  • "display_name": "string",
  • "name": "string",
  • "header": "string",
  • "purpose": "string",
  • "last_post_at": 0,
  • "total_msg_count": 0,
  • "extra_update_at": 0,
  • "creator_id": "string"
}

Create a group message channel

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

Permissions

Must have create_group_channel permission.

Authorizations:
bearerAuth
Request Body schema: application/json

User ids to be in the group message channel

Array
string

Responses

Request samples

Content type
application/json
[
  • "string"
]

Response samples

Content type
application/json
{
  • "id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "team_id": "string",
  • "type": "string",
  • "display_name": "string",
  • "name": "string",
  • "header": "string",
  • "purpose": "string",
  • "last_post_at": 0,
  • "total_msg_count": 0,
  • "extra_update_at": 0,
  • "creator_id": "string"
}

Search all private and open type channels across all teams

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

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

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

Authorizations:
bearerAuth
query Parameters
system_console
boolean
Default: true

Is the request from system_console. If this is set to true, it filters channels by the logged in user.

Request Body schema: application/json

The search terms and logic to use in the search.

term
required
string

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

not_associated_to_group
string

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

exclude_default_channels
boolean

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

team_ids
Array of strings

Filters results to channels belonging to the given team ids

Minimum server version: 5.26

group_constrained
boolean

Filters results to only return channels constrained to a group

Minimum server version: 5.26

exclude_group_constrained
boolean

Filters results to exclude channels constrained to a group

Minimum server version: 5.26

public
boolean

Filters results to only return Public / Open channels, can be used in conjunction with private to return both public and private channels

Minimum server version: 5.26

private
boolean

Filters results to only return Private channels, can be used in conjunction with public to return both private and public channels

Minimum server version: 5.26

deleted
boolean

Filters results to only return deleted / archived channels

Minimum server version: 5.26

page
string

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

per_page
string

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

exclude_policy_constrained
boolean
Default: false

If set to true, only channels which do not have a granular retention policy assigned to them will be returned. The sysconsole_read_compliance_data_retention permission is required to use this parameter. Minimum server version: 5.35

include_search_by_id
boolean
Default: false

If set to true, returns channels where given search 'term' matches channel ID. Minimum server version: 5.35

Responses

Request samples

Content type
application/json
{
  • "term": "string",
  • "not_associated_to_group": "string",
  • "exclude_default_channels": true,
  • "team_ids": [
    ],
  • "group_constrained": true,
  • "exclude_group_constrained": true,
  • "public": true,
  • "private": true,
  • "deleted": true,
  • "page": "string",
  • "per_page": "string",
  • "exclude_policy_constrained": false,
  • "include_search_by_id": false
}

Response samples

Content type
application/json
{
  • "channels": [
    ],
  • "total_count": 0
}

Search Group Channels

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

Minimum server version: 5.14

Authorizations:
bearerAuth
Request Body schema: application/json

Search criteria

term
required
string

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

Responses

Request samples

Content type
application/json
{
  • "term": "string"
}

Response samples

Content type
application/json
[
  • {
    }
]

Get a list of channels by ids

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

Permissions

view_team for the team the channels are on.

Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

Request Body schema: application/json

List of channel ids

Array
string

Responses

Request samples

Content type
application/json
[
  • "string"
]

Response samples

Content type
application/json
[
  • {
    }
]

Get timezones in a channel

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

Minimum server version: 5.6

Permissions

Must have the read_channel permission.

Authorizations:
bearerAuth
path Parameters
channel_id
required
string

Channel GUID

Responses

Request samples

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/mattermost/mattermost/server/public/model"
)

func main() {
	client := model.NewAPIv4Client(os.Getenv("MM_SERVICESETTINGS_SITEURL"))
	client.SetToken(os.Getenv("MM_AUTHTOKEN"))

	channelId := "channel_id"
	memberTimezones, _, err := client.GetChannelMembersTimezones(context.Background(), channelId)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Found %d timezones used by members of the channel %s\n", len(memberTimezones), channelId)
}

Response samples

Content type
application/json
[
  • "string"
]

Get a channel

Get channel from the provided channel id string.

Permissions

read_channel permission for the channel.

Authorizations:
bearerAuth
path Parameters
channel_id
required
string

Channel GUID

Responses

Request samples

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/mattermost/mattermost/server/public/model"
)

func main() {
	client := model.NewAPIv4Client(os.Getenv("MM_SERVICESETTINGS_SITEURL"))
	client.SetToken(os.Getenv("MM_AUTHTOKEN"))

	channelId := "channel_id"
	etag := ""
	channel, _, err := client.GetChannel(context.Background(), channelId, etag)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Found channel with name %s\n", channel.Name)
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "team_id": "string",
  • "type": "string",
  • "display_name": "string",
  • "name": "string",
  • "header": "string",
  • "purpose": "string",
  • "last_post_at": 0,
  • "total_msg_count": 0,
  • "extra_update_at": 0,
  • "creator_id": "string"
}

Update a channel

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

Permissions

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

Authorizations:
bearerAuth
path Parameters
channel_id
required
string

Channel GUID

Request Body schema: application/json

Channel object to be updated

id
required
string

The channel's id, not updatable

name
string

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

display_name
string

The non-unique UI name for the channel

purpose
string

A short description of the purpose of the channel

header
string

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

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "team_id": "string",
  • "type": "string",
  • "display_name": "string",
  • "name": "string",
  • "header": "string",
  • "purpose": "string",
  • "last_post_at": 0,
  • "total_msg_count": 0,
  • "extra_update_at": 0,
  • "creator_id": "string"
}

Delete a channel

Archives a channel. This will set the deleteAt to the current timestamp in the database. Soft deleted channels may not be accessible in the user interface. They can be viewed and unarchived in the System Console > User Management > Channels based on your license. Direct and group message channels cannot be deleted.

As of server version 5.28, optionally use the permanent=true query parameter to permanently delete the channel for compliance reasons. To use this feature ServiceSettings.EnableAPIChannelDeletion must be set to true in the server's configuration. If you permanently delete a channel this action is not recoverable outside of a database backup.

Permissions

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

Authorizations:
bearerAuth
path Parameters
channel_id
required
string

Channel GUID

Responses

Request samples

package main

import (
	"context"
	"log"
	"os"

	"github.com/mattermost/mattermost/server/public/model"
)

func main() {
	client := model.NewAPIv4Client(os.Getenv("MM_SERVICESETTINGS_SITEURL"))
	client.SetToken(os.Getenv("MM_AUTHTOKEN"))

	channelId := "channel_id"
	_, err := client.DeleteChannel(context.Background(), channelId)
	if err != nil {
		log.Fatal(err)
	}
}

Response samples

Content type
application/json
{
  • "status": "string"
}

Patch a channel

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

Permissions

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

Authorizations:
bearerAuth
path Parameters
channel_id
required
string

Channel GUID

Request Body schema: application/json

Channel object to be updated

name
string

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

display_name
string

The non-unique UI name for the channel

purpose
string

A short description of the purpose of the channel

header
string

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

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "team_id": "string",
  • "type": "string",
  • "display_name": "string",
  • "name": "string",
  • "header": "string",
  • "purpose": "string",
  • "last_post_at": 0,
  • "total_msg_count": 0,
  • "extra_update_at": 0,
  • "creator_id": "string"
}

Update channel's privacy

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

Minimum server version: 5.16

Permissions

manage_team permission for the channels team on version < 5.28. convert_public_channel_to_private permission for the channel if updating privacy to 'P' on version >= 5.28. convert_private_channel_to_public permission for the channel if updating privacy to 'O' on version >= 5.28.

Authorizations:
bearerAuth
path Parameters
channel_id
required
string

Channel GUID

Request Body schema: application/json
privacy
required
string

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

Responses

Request samples

Content type
application/json
{
  • "privacy": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "team_id": "string",
  • "type": "string",
  • "display_name": "string",
  • "name": "string",
  • "header": "string",
  • "purpose": "string",
  • "last_post_at": 0,
  • "total_msg_count": 0,
  • "extra_update_at": 0,
  • "creator_id": "string"
}

Restore a channel

Restore channel from the provided channel id string.

Minimum server version: 3.10

Permissions

manage_team permission for the team of the channel.

Authorizations:
bearerAuth
path Parameters
channel_id
required
string

Channel GUID

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "team_id": "string",
  • "type": "string",
  • "display_name": "string",
  • "name": "string",
  • "header": "string",
  • "purpose": "string",
  • "last_post_at": 0,
  • "total_msg_count": 0,
  • "extra_update_at": 0,
  • "creator_id": "string"
}

Move a channel

Move a channel to another team.

Minimum server version: 5.26

Permissions

Must have manage_system permission.

Authorizations:
bearerAuth
path Parameters
channel_id
required
string

Channel GUID

Request Body schema: application/json
team_id
required
string
force
boolean

Remove members those are not member of target team before moving the channel.

Responses

Request samples

Content type
application/json
{
  • "team_id": "string",
  • "force": true
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "team_id": "string",
  • "type": "string",
  • "display_name": "string",
  • "name": "string",
  • "header": "string",
  • "purpose": "string",
  • "last_post_at": 0,
  • "total_msg_count": 0,
  • "extra_update_at": 0,
  • "creator_id": "string"
}

Get channel statistics

Get statistics for a channel.

Permissions

Must have the read_channel permission.

Authorizations:
bearerAuth
path Parameters
channel_id
required
string

Channel GUID

Responses

Request samples

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/mattermost/mattermost/server/public/model"
)

func main() {
	client := model.NewAPIv4Client(os.Getenv("MM_SERVICESETTINGS_SITEURL"))
	client.SetToken(os.Getenv("MM_AUTHTOKEN"))

	channelId := "channel_id"
	etag := ""
	excludeFilesCount := true
	stats, _, err := client.GetChannelStats(context.Background(), channelId, etag, excludeFilesCount)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Found %d members and %d guests in channel %s\n", stats.MemberCount, stats.GuestCount, channelId)
}

Response samples

Content type
application/json
{
  • "channel_id": "string",
  • "member_count": 0
}

Get a channel's pinned posts

Get a list of pinned posts for channel.

Authorizations:
bearerAuth
path Parameters
channel_id
required
string

Channel GUID

Responses

Request samples

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/mattermost/mattermost/server/public/model"
)

func main() {
	client := model.NewAPIv4Client(os.Getenv("MM_SERVICESETTINGS_SITEURL"))
	client.SetToken(os.Getenv("MM_AUTHTOKEN"))

	channelId := "channel_id"
	etag := ""
	posts, _, err := client.GetPinnedPosts(context.Background(), channelId, etag)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Found %d pinned posts for channel %s\n", len(posts.Posts), channelId)
}

Response samples

Content type
application/json
{
  • "order": [
    ],
  • "posts": {
    },
  • "next_post_id": "string",
  • "prev_post_id": "string",
  • "has_next": true
}

Get public channels

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

Permissions

Must be authenticated and have the list_team_channels permission.

Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

query Parameters
page
integer
Default: 0

The page to select.

per_page
integer
Default: 60

The number of public channels per page.

Responses

Request samples

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/mattermost/mattermost/server/public/model"
)

func main() {
	client := model.NewAPIv4Client(os.Getenv("MM_SERVICESETTINGS_SITEURL"))
	client.SetToken(os.Getenv("MM_AUTHTOKEN"))

	teamId := "team_id"
	page := 0
	perPage := 100
	etag := ""
	channels, _, err := client.GetPublicChannelsForTeam(context.Background(), teamId, page, perPage, etag)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Found %d public channels for team %s\n", len(channels), teamId)
}

Response samples

Content type
application/json
[
  • {
    }
]

Get private channels

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

Minimum server version: 5.26

Permissions

Must have manage_system permission.

Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

query Parameters
page
integer
Default: 0

The page to select.

per_page
integer
Default: 60

The number of private channels per page.

Responses

Request samples

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/mattermost/mattermost/server/public/model"
)

func main() {
	client := model.NewAPIv4Client(os.Getenv("MM_SERVICESETTINGS_SITEURL"))
	client.SetToken(os.Getenv("MM_AUTHTOKEN"))

	teamId := "team_id"
	page := 0
	perPage := 100
	etag := ""
	channels, _, err := client.GetPrivateChannelsForTeam(context.Background(), teamId, page, perPage, etag)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Found %d private channels for team %s\n", len(channels), teamId)
}

Response samples

Content type
application/json
[
  • {
    }
]

Get deleted channels

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

Minimum server version: 3.10

Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

query Parameters
page
integer
Default: 0

The page to select.

per_page
integer
Default: 60

The number of public channels per page.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Autocomplete channels

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

Minimum server version: 4.7

Permissions

Must have the list_team_channels permission.

Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

query Parameters
name
required
string

Name or display name

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Autocomplete channels for search

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

Minimum server version: 5.4

Permissions

Must have the list_team_channels permission.

Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

query Parameters
name
required
string

Name or display name

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Search channels

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

Permissions

Must have the list_team_channels permission.

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

Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

Request Body schema: application/json

Search criteria

term
required
string

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

Responses

Request samples

Content type
application/json
{
  • "term": "string"
}

Response samples

Content type
application/json
[
  • {
    }
]

Search archived channels

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

Minimum server version: 5.18

Permissions

Must have the list_team_channels permission.

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

Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

Request Body schema: application/json

Search criteria

term
required
string

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

Responses

Request samples

Content type
application/json
{
  • "term": "string"
}

Response samples

Content type
application/json
[
  • {
    }
]

Get a channel by name

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

Permissions

read_channel permission for the channel.

Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

channel_name
required
string

Channel Name

query Parameters
include_deleted
boolean
Default: false

Defines if deleted channels should be returned or not (Mattermost Server 5.26.0+)

Responses

Request samples

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/mattermost/mattermost/server/public/model"
)

func main() {
	client := model.NewAPIv4Client(os.Getenv("MM_SERVICESETTINGS_SITEURL"))
	client.SetToken(os.Getenv("MM_AUTHTOKEN"))

	channelName := "channel_name"
	teamId := "team_id"
	etag := ""
	channel, _, err := client.GetChannelByName(context.Background(), channelName, teamId, etag)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Found channel %s with name %s\n", channel.Id, channel.Name)
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "team_id": "string",
  • "type": "string",
  • "display_name": "string",
  • "name": "string",
  • "header": "string",
  • "purpose": "string",
  • "last_post_at": 0,
  • "total_msg_count": 0,
  • "extra_update_at": 0,
  • "creator_id": "string"
}

Get a channel by name and team name

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

Permissions

read_channel permission for the channel.

Authorizations:
bearerAuth
path Parameters
team_name
required
string

Team Name

channel_name
required
string

Channel Name

query Parameters
include_deleted
boolean
Default: false

Defines if deleted channels should be returned or not (Mattermost Server 5.26.0+)

Responses

Request samples

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/mattermost/mattermost/server/public/model"
)

func main() {
	client := model.NewAPIv4Client(os.Getenv("MM_SERVICESETTINGS_SITEURL"))
	client.SetToken(os.Getenv("MM_AUTHTOKEN"))

	channelName := "channel_name"
	teamName := "team_name"
	etag := ""
	channel, _, err := client.GetChannelByNameForTeamName(context.Background(), channelName, teamName, etag)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Found channel %s with name %s\n", channel.Id, channel.Name)
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "team_id": "string",
  • "type": "string",
  • "display_name": "string",
  • "name": "string",
  • "header": "string",
  • "purpose": "string",
  • "last_post_at": 0,
  • "total_msg_count": 0,
  • "extra_update_at": 0,
  • "creator_id": "string"
}

Get channel members

Get a page of members for a channel.

Permissions

read_channel permission for the channel.

Authorizations:
bearerAuth
path Parameters
channel_id
required
string

Channel GUID

query Parameters
page
integer
Default: 0

The page to select.

per_page
integer
Default: 60

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

Responses

Request samples

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/mattermost/mattermost/server/public/model"
)

func main() {
	client := model.NewAPIv4Client(os.Getenv("MM_SERVICESETTINGS_SITEURL"))
	client.SetToken(os.Getenv("MM_AUTHTOKEN"))

	channelId := "channel_id"
	page := 0
	perPage := 60
	etag := ""
	members, _, err := client.GetChannelMembers(context.Background(), channelId, page, perPage, etag)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Found %d channel members for channel %s\n", len(members), channelId)
}

Response samples

Content type
application/json
[
  • {
    }
]

Add user to channel

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

Authorizations:
bearerAuth
path Parameters
channel_id
required
string

The channel ID

Request Body schema: application/json
user_id
required
string

The ID of user to add into the channel

post_root_id
string

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

Responses

Request samples

Content type
application/json
{
  • "user_id": "string",
  • "post_root_id": "string"
}

Response samples

Content type
application/json
{
  • "channel_id": "string",
  • "user_id": "string",
  • "roles": "string",
  • "last_viewed_at": 0,
  • "msg_count": 0,
  • "mention_count": 0,
  • "notify_props": {
    },
  • "last_update_at": 0
}

Get channel members by ids

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

Permissions

Must have the read_channel permission.

Authorizations:
bearerAuth
path Parameters
channel_id
required
string

Channel GUID

Request Body schema: application/json

List of user ids

Array
string

Responses

Request samples

Content type
application/json
[
  • "string"
]

Response samples

Content type
application/json
[
  • {
    }
]

Get channel member

Get a channel member.

Permissions

read_channel permission for the channel.

Authorizations:
bearerAuth
path Parameters
channel_id
required
string

Channel GUID

user_id
required
string

User GUID

Responses

Request samples

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/mattermost/mattermost/server/public/model"
)

func main() {
	client := model.NewAPIv4Client(os.Getenv("MM_SERVICESETTINGS_SITEURL"))
	client.SetToken(os.Getenv("MM_AUTHTOKEN"))

	channelId := "channel_id"
	userId := "user_id"
	etag := ""
	member, _, err := client.GetChannelMember(context.Background(), channelId, userId, etag)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Found channel member for user %s in channel %s having roles %s\n", userId, channelId, member.Roles)
}

Response samples

Content type
application/json
{
  • "channel_id": "string",
  • "user_id": "string",
  • "roles": "string",
  • "last_viewed_at": 0,
  • "msg_count": 0,
  • "mention_count": 0,
  • "notify_props": {
    },
  • "last_update_at": 0
}

Remove user from channel

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

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

Permissions

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

Authorizations:
bearerAuth
path Parameters
channel_id
required
string

Channel GUID

user_id
required
string

User GUID

Responses

Request samples

package main

import (
	"context"
	"log"
	"os"

	"github.com/mattermost/mattermost/server/public/model"
)

func main() {
	client := model.NewAPIv4Client(os.Getenv("MM_SERVICESETTINGS_SITEURL"))
	client.SetToken(os.Getenv("MM_AUTHTOKEN"))

	channelId := "channel_id"
	userId := "user_id"
	_, err := client.RemoveUserFromChannel(context.Background(), channelId, userId)
	if err != nil {
		log.Fatal(err)
	}
}

Response samples

Content type
application/json
{
  • "status": "string"
}

Update channel roles

Update a user's roles for a channel.

Permissions

Must have manage_channel_roles permission for the channel.

Authorizations:
bearerAuth
path Parameters
channel_id
required
string

Channel GUID

user_id
required
string

User GUID

Request Body schema: application/json

Space-delimited channel roles to assign to the user

roles
required
string

Responses

Request samples

Content type
application/json
{
  • "roles": "string"
}

Response samples

Content type
application/json
{
  • "status": "string"
}

Update the scheme-derived roles of a channel member.

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

Permissions

Must be authenticated and have the manage_channel_roles permission.

Authorizations:
bearerAuth
path Parameters
channel_id
required
string

Channel GUID

user_id
required
string

User GUID

Request Body schema: application/json

Scheme properties.

scheme_admin
required
boolean
scheme_user
required
boolean

Responses

Request samples

Content type
application/json
{
  • "scheme_admin": true,
  • "scheme_user": true
}

Response samples

Content type
application/json
{
  • "status": "string"
}

Update channel notifications

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

Permissions

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

Authorizations:
bearerAuth
path Parameters
channel_id
required
string

Channel GUID

user_id
required
string

User GUID

Request Body schema: application/json
email
string

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

push
string

Set to "all" to receive push notifications for all activity, "mention" for mentions and direct messages only, "none" to disable, or "default" to use the global user notification setting.

desktop
string

Set to "all" to receive desktop notifications for all activity, "mention" for mentions and direct messages only, "none" to disable, or "default" to use the global user notification setting.

mark_unread
string

Set to "all" to mark the channel unread for any new message, "mention" to mark unread for new mentions only. Defaults to "all".

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "push": "string",
  • "desktop": "string",
  • "mark_unread": "string"
}

Response samples

Content type
application/json
{
  • "status": "string"
}

View channel

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

Permissions

Must be logged in as user or have edit_other_users permission.

Response only includes last_viewed_at_times in Mattermost server 4.3 and newer.

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User ID to perform the view action for

Request Body schema: application/json

Paremeters affecting how and which channels to view

channel_id
required
string

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

prev_channel_id
string

The channel ID of the previous channel, used when switching channels. Providing this ID will cause push notifications to clear on the channel being switched to.

Responses

Request samples

Content type
application/json
{
  • "channel_id": "string",
  • "prev_channel_id": "string"
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "last_viewed_at_times": { }
}

Get channel memberships and roles for a user

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

Permissions

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

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

team_id
required
string

Team GUID

Responses

Request samples

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/mattermost/mattermost/server/public/model"
)

func main() {
	client := model.NewAPIv4Client(os.Getenv("MM_SERVICESETTINGS_SITEURL"))
	client.SetToken(os.Getenv("MM_AUTHTOKEN"))

	userId := "user_id"
	teamId := "team_id"
	etag := ""
	members, _, err := client.GetChannelMembersForUser(context.Background(), userId, teamId, etag)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Found %d channel members for user %s on team %s\n", len(members), userId, teamId)
}

Response samples

Content type
application/json
[
  • {
    }
]

Get channels for user

Get all the channels on a team for a user.

Permissions

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

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

team_id
required
string

Team GUID

query Parameters
include_deleted
boolean
Default: false

Defines if deleted channels should be returned or not

last_delete_at
integer
Default: 0

Filters the deleted channels by this time in epoch format. Does not have any effect if include_deleted is set to false.

Responses

Request samples

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/mattermost/mattermost/server/public/model"
)

func main() {
	client := model.NewAPIv4Client(os.Getenv("MM_SERVICESETTINGS_SITEURL"))
	client.SetToken(os.Getenv("MM_AUTHTOKEN"))

	userId := "user_id"
	teamId := "team_id"
	includeDeleted := false
	etag := ""
	channels, _, err := client.GetChannelsForTeamForUser(context.Background(), teamId, userId, includeDeleted, etag)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Found %d channels for user %s on team %s\n", len(channels), userId, teamId)
}

Response samples

Content type
application/json
[
  • {
    }
]

Get all channels from all teams

Get all channels from all teams that a user is a member of.

Minimum server version: 6.1

Permissions

Logged in as the user, or have edit_other_users permission.

Authorizations:
bearerAuth
path Parameters
user_id
required
string

The ID of the user. This can also be "me" which will point to the current user.

query Parameters
last_delete_at
integer
Default: 0

Filters the deleted channels by this time in epoch format. Does not have any effect if include_deleted is set to false.

include_deleted
boolean
Default: false

Defines if deleted channels should be returned or not

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get unread messages

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

Permissions

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

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

channel_id
required
string

Channel GUID

Responses

Request samples

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/mattermost/mattermost/server/public/model"
)

func main() {
	client := model.NewAPIv4Client(os.Getenv("MM_SERVICESETTINGS_SITEURL"))
	client.SetToken(os.Getenv("MM_AUTHTOKEN"))

	channelId := "channel_id"
	userId := "user_id"
	channelUnread, _, err := client.GetChannelUnread(context.Background(), channelId, userId)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Found %d unread messages with %d mentions for user %s in channel %s\n", channelUnread.MentionCount, channelUnread.MentionCount, userId, channelId)
}

Response samples

Content type
application/json
{
  • "team_id": "string",
  • "channel_id": "string",
  • "msg_count": 0,
  • "mention_count": 0
}

Set a channel's scheme

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

Permissions

Must have manage_system permission.

Minimum server version: 4.10

Authorizations:
bearerAuth
path Parameters
channel_id
required
string

Channel GUID

Request Body schema: application/json

Scheme GUID

scheme_id
required
string

The ID of the scheme.

Responses

Request samples

Content type
application/json
{
  • "scheme_id": "string"
}

Response samples

Content type
application/json
{
  • "status": "string"
}

Channel members minus group members.

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

Permissions

Must have manage_system permission.

Minimum server version: 5.14

Authorizations:
bearerAuth
path Parameters
channel_id
required
string

Channel GUID

query Parameters
group_ids
required
string
Default: ""

A comma-separated list of group ids.

page
integer
Default: 0

The page to select.

per_page
integer
Default: 0

The number of users per page.

Responses

Response samples

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

Channel members counts for each group that has atleast one member in the channel

Returns a set of ChannelMemberCountByGroup objects which contain a group_id, channel_member_count and a channel_member_timezones_count.

Permissions

Must have read_channel permission for the given channel. Minimum server version: 5.24

Authorizations:
bearerAuth
path Parameters
channel_id
required
string

Channel GUID

query Parameters
include_timezones
boolean
Default: false

Defines if member timezone counts should be returned or not

Responses

Response samples

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

Get information about channel's moderation.

Permissions

Must have manage_system permission.

Minimum server version: 5.22

Authorizations:
bearerAuth
path Parameters
channel_id
required
string

Channel GUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update a channel's moderation settings.

Permissions

Must have manage_system permission.

Minimum server version: 5.22

Authorizations:
bearerAuth
path Parameters
channel_id
required
string

Channel GUID

Request Body schema: application/json
name
string
object (ChannelModeratedRolesPatch)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "roles": {
    }
}

Response samples

Content type
application/json
[
  • {
    }
]

Get user's sidebar categories

Get a list of sidebar categories that will appear in the user's sidebar on the given team, including a list of channel IDs in each category. Minimum server version: 5.26

Permissions

Must be authenticated and have the list_team_channels permission.

Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

user_id
required
string

User GUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create user's sidebar category

Create a custom sidebar category for the user on the given team. Minimum server version: 5.26

Permissions

Must be authenticated and have the list_team_channels permission.

Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

user_id
required
string

User GUID

Request Body schema: application/json
id
string
user_id
string
team_id
string
display_name
string
type
string
Enum: "channels" "custom" "direct_messages" "favorites"

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "user_id": "string",
  • "team_id": "string",
  • "display_name": "string",
  • "type": "channels"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "user_id": "string",
  • "team_id": "string",
  • "display_name": "string",
  • "type": "channels"
}

Update user's sidebar categories

Update any number of sidebar categories for the user on the given team. This can be used to reorder the channels in these categories. Minimum server version: 5.26

Permissions

Must be authenticated and have the list_team_channels permission.

Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

user_id
required
string

User GUID

Request Body schema: application/json
Array
id
string
user_id
string
team_id
string
display_name
string
type
string
Enum: "channels" "custom" "direct_messages" "favorites"

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "id": "string",
  • "user_id": "string",
  • "team_id": "string",
  • "display_name": "string",
  • "type": "channels"
}

Get user's sidebar category order

Returns the order of the sidebar categories for a user on the given team as an array of IDs. Minimum server version: 5.26

Permissions

Must be authenticated and have the list_team_channels permission.

Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

user_id
required
string

User GUID

Responses

Response samples

Content type
application/json
[
  • "string"
]

Update user's sidebar category order

Updates the order of the sidebar categories for a user on the given team. The provided array must include the IDs of all categories on the team. Minimum server version: 5.26

Permissions

Must be authenticated and have the list_team_channels permission.

Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

user_id
required
string

User GUID

Request Body schema: application/json
Array
string

Responses

Request samples

Content type
application/json
[
  • "string"
]

Response samples

Content type
application/json
[
  • "string"
]

Get sidebar category

Returns a single sidebar category for the user on the given team. Minimum server version: 5.26

Permissions

Must be authenticated and have the list_team_channels permission.

Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

user_id
required
string

User GUID

category_id
required
string

Category GUID

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "user_id": "string",
  • "team_id": "string",
  • "display_name": "string",
  • "type": "channels"
}

Update sidebar category

Updates a single sidebar category for the user on the given team. Minimum server version: 5.26

Permissions

Must be authenticated and have the list_team_channels permission.

Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

user_id
required
string

User GUID

category_id
required
string

Category GUID

Request Body schema: application/json
id
string
user_id
string
team_id
string
display_name
string
type
string
Enum: "channels" "custom" "direct_messages" "favorites"

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "user_id": "string",
  • "team_id": "string",
  • "display_name": "string",
  • "type": "channels"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "user_id": "string",
  • "team_id": "string",
  • "display_name": "string",
  • "type": "channels"
}

Delete sidebar category

Deletes a single sidebar category for the user on the given team. Only custom categories can be deleted. Minimum server version: 5.26

Permissions

Must be authenticated and have the list_team_channels permission.

Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

user_id
required
string

User GUID

category_id
required
string

Category GUID

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "user_id": "string",
  • "team_id": "string",
  • "display_name": "string",
  • "type": "channels"
}

posts

Endpoints for creating, getting and interacting with posts.

Create a post

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

Permissions

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

Authorizations:
bearerAuth
query Parameters
set_online
boolean

Whether to set the user status as online or not.

Request Body schema: application/json

Post object to create

channel_id
required
string

The channel ID to post in

message
required
string

The message contents, can be formatted with Markdown

root_id
string

The post ID to comment on

file_ids
Array of strings

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

props
object

A general JSON property bag to attach to the post

object

A JSON object to add post metadata, e.g the post's priority

Responses

Request samples

Content type
application/json
{
  • "channel_id": "string",
  • "message": "string",
  • "root_id": "string",
  • "file_ids": [
    ],
  • "props": { },
  • "metadata": {
    }
}

Response samples

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

Create a ephemeral post

Create a new ephemeral post in a channel.

Permissions

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

Authorizations:
bearerAuth
Request Body schema: application/json

Ephemeral Post object to send

user_id
required
string

The target user id for the ephemeral post

required
object

Post object to create

Responses

Request samples

Content type
application/json
{
  • "user_id": "string",
  • "post": {
    }
}

Response samples

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

Get a post

Get a single post.

Permissions

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

Authorizations:
bearerAuth
path Parameters
post_id
required
string

ID of the post to get

query Parameters
include_deleted
boolean
Default: false

Defines if result should include deleted posts, must have 'manage_system' (admin) permission.

Responses

Response samples

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

Delete a post

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

Permissions

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

Authorizations:
bearerAuth
path Parameters
post_id
required
string

ID of the post to delete

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Update a post

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

Permissions

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

Authorizations:
bearerAuth
path Parameters
post_id
required
string

ID of the post to update

Request Body schema: application/json

Post object that is to be updated

id
required
string

ID of the post to update

is_pinned
boolean

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

message
string

The message text of the post

has_reactions
boolean

Set to true if the post has reactions to it

props
string

A general JSON property bag to attach to the post

Responses

Request samples

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

Response samples

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

Mark as unread from a post.

Mark a channel as being unread from a given post.

Permissions

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

Minimum server version: 5.18

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

post_id
required
string

Post GUID

Responses

Response samples

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

Patch a post

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

Permissions

Must have the edit_post permission.

Authorizations:
bearerAuth
path Parameters
post_id
required
string

Post GUID

Request Body schema: application/json

Post object that is to be updated

is_pinned
boolean

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

message
string

The message text of the post

file_ids
Array of strings

The list of files attached to this post

has_reactions
boolean

Set to true if the post has reactions to it

props
string

A general JSON property bag to attach to the post

Responses

Request samples

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

Response samples

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

Get a thread

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

Permissions

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

Authorizations:
bearerAuth
path Parameters
post_id
required
string

ID of a post in the thread

query Parameters
perPage
integer
Default: 0

The number of posts per page

fromPost
string
Default: ""

The post_id to return the next page of posts from

fromCreateAt
integer
Default: 0

The create_at timestamp to return the next page of posts from

direction
string
Default: ""

The direction to return the posts. Either up or down.

skipFetchThreads
boolean
Default: false

Whether to skip fetching threads or not

collapsedThreads
boolean
Default: false

Whether the client uses CRT or not

collapsedThreadsExtended
boolean
Default: false

Whether to return the associated users as part of the response or not

Responses

Response samples

Content type
application/json
{
  • "order": [
    ],
  • "posts": {
    },
  • "next_post_id": "string",
  • "prev_post_id": "string",
  • "has_next": true
}

Get a list of flagged posts

Get a page of flagged posts of a user provided user id string. Selects from a channel, team, or all flagged posts by a user. Will only return posts from channels in which the user is member.

Permissions

Must be user or have manage_system permission.

Authorizations:
bearerAuth
path Parameters
user_id
required
string

ID of the user

query Parameters
team_id
string

Team ID

channel_id
string

Channel ID

page
integer
Default: 0

The page to select

per_page
integer
Default: 60

The number of posts per page

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get file info for post

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

Permissions

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

Authorizations:
bearerAuth
path Parameters
post_id
required
string

ID of the post

query Parameters
include_deleted
boolean
Default: false

Defines if result should include deleted posts, must have 'manage_system' (admin) permission.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get posts for a channel

Get a page of posts in a channel. Use the query parameters to modify the behaviour of this endpoint. The parameter since must not be used with any of before, after, page, and per_page parameters. If since is used, it will always return all posts modified since that time, ordered by their create time limited till 1000. A caveat with this parameter is that there is no guarantee that the returned posts will be consecutive. It is left to the clients to maintain state and fill any missing holes in the post order.

Permissions

Must have read_channel permission for the channel.

Authorizations:
bearerAuth
path Parameters
channel_id
required
string

The channel ID to get the posts for

query Parameters
page
integer
Default: 0

The page to select

per_page
integer
Default: 60

The number of posts per page

since
integer

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

before
string

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

after
string

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

include_deleted
boolean
Default: false

Whether to include deleted posts or not. Must have system admin permissions.

Responses

Response samples

Content type
application/json
{
  • "order": [
    ],
  • "posts": {
    },
  • "next_post_id": "string",
  • "prev_post_id": "string",
  • "has_next": true
}

Get posts around oldest unread

Get the oldest unread post in the channel for the given user as well as the posts around it. The returned list is sorted in descending order (most recent post first).

Permissions

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

Authorizations:
bearerAuth
path Parameters
user_id
required
string

ID of the user

channel_id
required
string

The channel ID to get the posts for

query Parameters
limit_before
integer <= 200
Default: 60

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

limit_after
integer [ 1 .. 200 ]
Default: 60

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

skipFetchThreads
boolean
Default: false

Whether to skip fetching threads or not

collapsedThreads
boolean
Default: false

Whether the client uses CRT or not

collapsedThreadsExtended
boolean
Default: false

Whether to return the associated users as part of the response or not

Responses

Response samples

Content type
application/json
{
  • "order": [
    ],
  • "posts": {
    },
  • "next_post_id": "string",
  • "prev_post_id": "string",
  • "has_next": true
}

Search for team posts

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

Permissions

Must be authenticated and have the view_team permission.

Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

Request Body schema: application/json

The search terms and logic to use in the search.

terms
required
string

The search terms as inputed by the user. To search for posts from a user include from:someusername, using a user's username. To search in a specific channel include in:somechannel, using the channel name (not the display name).

is_or_search
required
boolean

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

time_zone_offset
integer
Default: 0

Offset from UTC of user timezone for date searches.

include_deleted_channels
boolean

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

page
integer
Default: 0

The page to select. (Only works with Elasticsearch)

per_page
integer
Default: 60

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

Responses

Request samples

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

Response samples

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

Pin a post to the channel

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

Permissions

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

Authorizations:
bearerAuth
path Parameters
post_id
required
string

Post GUID

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Unpin a post to the channel

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

Permissions

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

Authorizations:
bearerAuth
path Parameters
post_id
required
string

Post GUID

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Perform a post action

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

Permissions

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

Authorizations:
bearerAuth
path Parameters
post_id
required
string

Post GUID

action_id
required
string

Action GUID

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Get posts by a list of ids

Fetch a list of posts based on the provided postIDs

Permissions

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

Authorizations:
bearerAuth
Request Body schema: application/json

List of post ids

Array
string

Responses

Request samples

Content type
application/json
[
  • "string"
]

Response samples

Content type
application/json
[
  • {
    }
]

Set a post reminder

Set a reminder for the user for the post.

Permissions

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

Minimum server version: 7.2

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

post_id
required
string

Post GUID

Request Body schema: application/json

Target time for the reminder

target_time
required
integer

Target time for the reminder

Responses

Request samples

Content type
application/json
{
  • "target_time": 0
}

Response samples

Content type
application/json
{
  • "status": "string"
}

Acknowledge a post

Acknowledge a post that has a request for acknowledgements.

Permissions

Must have read_channel permission for the channel the post is in.
Must be logged in as the user or have edit_other_users permission.

Minimum server version: 7.7

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

post_id
required
string

Post GUID

Responses

Response samples

Content type
application/json
{
  • "user_id": "string",
  • "post_id": "string",
  • "acknowledged_at": 0
}

Delete a post acknowledgement

Delete an acknowledgement form a post that you had previously acknowledged.

Permissions

Must have read_channel permission for the channel the post is in.
Must be logged in as the user or have edit_other_users permission.
The post must have been acknowledged in the previous 5 minutes.

Minimum server version: 7.7

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

post_id
required
string

Post GUID

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Move a post (and any posts within that post's thread)

Move a post/thread to another channel. THIS IS A BETA FEATURE. The API is subject to change without notice.

Permissions

Must have read_channel permission for the channel the post is in. Must have write_post permission for the channel the post is being moved to.

Minimum server version: 9.3

Authorizations:
bearerAuth
path Parameters
post_id
required
string

The identifier of the post to move

Request Body schema: application/json

The channel identifier of where the post/thread is to be moved

channel_id
required
string

The channel identifier of where the post/thread is to be moved

Responses

Request samples

Content type
application/json
{
  • "channel_id": "string"
}

Response samples

Content type
application/json
{
  • "status": "string"
}

threads

Get all threads that user is following

Get all threads that user is following

Minimum server version: 5.29

Permissions

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

Authorizations:
bearerAuth
path Parameters
user_id
required
string

The ID of the user. This can also be "me" which will point to the current user.

team_id
required
string

The ID of the team in which the thread is.

query Parameters
since
integer

Since filters the threads based on their LastUpdateAt timestamp.

deleted
boolean
Default: false

Deleted will specify that even deleted threads should be returned (For mobile sync).

extended
boolean
Default: false

Extended will enrich the response with participant details.

page
integer
Default: 0

Page specifies which part of the results to return, by PageSize.

pageSize
integer
Default: 30

PageSize specifies the size of the returned chunk of results.

totalsOnly
boolean
Default: false

Setting this to true will only return the total counts.

threadsOnly
boolean
Default: false

Setting this to true will only return threads.

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "threads": [
    ]
}

Get all unread mention counts from followed threads, per-channel

Get all unread mention counts from followed threads

Minimum server version: 5.29

Permissions

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

Authorizations:
bearerAuth
path Parameters
user_id
required
string

The ID of the user. This can also be "me" which will point to the current user.

team_id
required
string

The ID of the team in which the thread is.

Responses

Response samples

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

Mark all threads that user is following as read

Mark all threads that user is following as read

Minimum server version: 5.29

Permissions

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

Authorizations:
bearerAuth
path Parameters
user_id
required
string

The ID of the user. This can also be "me" which will point to the current user.

team_id
required
string

The ID of the team in which the thread is.

Responses

Response samples

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

Mark a thread that user is following read state to the timestamp

Mark a thread that user is following as read

Minimum server version: 5.29

Permissions

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

Authorizations:
bearerAuth
path Parameters
user_id
required
string

The ID of the user. This can also be "me" which will point to the current user.

team_id
required
string

The ID of the team in which the thread is.

thread_id
required
string

The ID of the thread to update

timestamp
required
string

The timestamp to which the thread's "last read" state will be reset.

Responses

Response samples

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

Mark a thread that user is following as unread based on a post id

Mark a thread that user is following as unread

Minimum server version: 6.7

Permissions

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

Must have edit_other_users permission if the user is not the one marking the thread for himself.

Authorizations:
bearerAuth
path Parameters
user_id
required
string

The ID of the user. This can also be "me" which will point to the current user.

team_id
required
string

The ID of the team in which the thread is.

thread_id
required
string

The ID of the thread to update

post_id
required
string

The ID of a post belonging to the thread to mark as unread.

Responses

Response samples

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

Start following a thread

Start following a thread

Minimum server version: 5.29

Permissions

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

Authorizations:
bearerAuth
path Parameters
user_id
required
string

The ID of the user. This can also be "me" which will point to the current user.

team_id
required
string

The ID of the team in which the thread is.

thread_id
required
string

The ID of the thread to follow

Responses

Response samples

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

Stop following a thread

Stop following a thread

Minimum server version: 5.29

Permissions

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

Authorizations:
bearerAuth
path Parameters
user_id
required
string

The ID of the user. This can also be "me" which will point to the current user.

team_id
required
string

The ID of the team in which the thread is.

thread_id
required
string

The ID of the thread to update

Responses

Response samples

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

Get a thread followed by the user

Get a thread

Minimum server version: 5.29

Permissions

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

Authorizations:
bearerAuth
path Parameters
user_id
required
string

The ID of the user. This can also be "me" which will point to the current user.

team_id
required
string

The ID of the team in which the thread is.

thread_id
required
string

The ID of the thread to follow

Responses

Response samples

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

files

Endpoints for uploading and interacting with files.

Upload a file

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

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

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

Minimum server version: 9.4 Starting with server version 9.4 when uploading a file for a channel bookmark, the bookmark=true query parameter should be included in the query string

Permissions

Must have upload_file permission.

Authorizations:
bearerAuth
query Parameters
channel_id
string

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

filename
string

The name of the file to be uploaded

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

A file to be uploaded

channel_id
string

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

client_ids
string

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

Responses

Response samples

Content type
application/json
{
  • "file_infos": [
    ],
  • "client_ids": [
    ]
}

Get a file

Gets a file that has been uploaded previously.

Permissions

Must have read_channel permission or be uploader of the file.

Authorizations:
bearerAuth
path Parameters
file_id
required
string

The ID of the file to get

Responses

Response samples

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

Get a file's thumbnail

Gets a file's thumbnail.

Permissions

Must have read_channel permission or be uploader of the file.

Authorizations:
bearerAuth
path Parameters
file_id
required
string

The ID of the file to get

Responses

Response samples

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

Get a file's preview

Gets a file's preview.

Permissions

Must have read_channel permission or be uploader of the file.

Authorizations:
bearerAuth
path Parameters
file_id
required
string

The ID of the file to get

Responses

Response samples

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

Get metadata for a file

Gets a file's info.

Permissions

Must have read_channel permission or be uploader of the file.

Authorizations:
bearerAuth
path Parameters
file_id
required
string

The ID of the file info to get

Responses

Response samples

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

Get a public file

Permissions

No permissions required.

Authorizations:
bearerAuth
path Parameters
file_id
required
string

The ID of the file to get

query Parameters
h
required
string

File hash

Responses

Response samples

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

Search files in a team

Search for files in a team based on file name, extention and file content (if file content extraction is enabled and supported for the files). Minimum server version: 5.34

Permissions

Must be authenticated and have the view_team permission.

Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

Request Body schema: multipart/form-data

The search terms and logic to use in the search.

terms
required
string

The search terms as inputed by the user. To search for files from a user include from:someusername, using a user's username. To search in a specific channel include in:somechannel, using the channel name (not the display name). To search for specific extensions included ext:extension.

is_or_search
required
boolean

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

time_zone_offset
integer
Default: 0

Offset from UTC of user timezone for date searches.

include_deleted_channels
boolean

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

page
integer
Default: 0

The page to select. (Only works with Elasticsearch)

per_page
integer
Default: 60

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

Responses

Response samples

Content type
application/json
{
  • "order": [
    ],
  • "file_infos": {
    },
  • "next_file_id": "string",
  • "prev_file_id": "string"
}

uploads

Endpoints for creating and performing file uploads.

Create an upload

Creates a new upload session.

Minimum server version: 5.28

Permissions

Must have upload_file permission.

Authorizations:
bearerAuth
Request Body schema: application/json
channel_id
required
string

The ID of the channel to upload to.

filename
required
string

The name of the file to upload.

file_size
required
integer <int64>

The size of the file to upload in bytes.

Responses

Request samples

Content type
application/json
{
  • "channel_id": "string",
  • "filename": "string",
  • "file_size": 0
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "attachment",
  • "create_at": 0,
  • "user_id": "string",
  • "channel_id": "string",
  • "filename": "string",
  • "file_size": 0,
  • "file_offset": 0
}

Get an upload session

Gets an upload session that has been previously created.

Permissions

Must be logged in as the user who created the upload session.

Authorizations:
bearerAuth
path Parameters
upload_id
required
string

The ID of the upload session to get.

Responses

Response samples

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

Perform a file upload

Starts or resumes a file upload.
To resume an existing (incomplete) upload, data should be sent starting from the offset specified in the upload session object.

The request body can be in one of two formats:

  • Binary file content streamed in request's body
  • multipart/form-data
Permissions

Must be logged in as the user who created the upload session.

Authorizations:
bearerAuth
path Parameters
upload_id
required
string

The ID of the upload session the data belongs to.

Request Body schema: application/x-www-form-urlencoded
object

Responses

Response samples

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

bookmarks

Endpoints for creating, getting and interacting with channel bookmarks.

Get channel bookmarks for Channel

Minimum server version: 9.5

Authorizations:
bearerAuth
path Parameters
channel_id
required
string

Channel GUID

query Parameters
bookmarks_since
number <int64>

Timestamp to filter the bookmarks with. If set, the endpoint returns bookmarks that have been added, updated or deleted since its value

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create channel bookmark

Creates a new channel bookmark for this channel.

Minimum server version: 9.5

Permissions

Must have the add_bookmark_public_channel or add_bookmark_private_channel depending on the channel type. If the channel is a DM or GM, must be a non-guest member.

Authorizations:
bearerAuth
path Parameters
channel_id
required
string

Channel GUID

Request Body schema: application/json

Channel Bookmark object to be created

file_id
string

The ID of the file associated with the channel bookmark. Required for bookmarks of type 'file'

display_name
required
string

The name of the channel bookmark

link_url
string

The URL associated with the channel bookmark. Required for bookmarks of type 'link'

image_url
string

The URL of the image associated with the channel bookmark. Optional, only applies for bookmarks of type 'link'

emoji
string

The emoji of the channel bookmark

type
required
string
Enum: "link" "file"
  • link for channel bookmarks that reference a link. link_url is requied
  • file for channel bookmarks that reference a file. file_id is required

Responses

Request samples

Content type
application/json
{
  • "file_id": "string",
  • "display_name": "string",
  • "link_url": "string",
  • "image_url": "string",
  • "emoji": "string",
  • "type": "link"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "channel_id": "string",
  • "owner_id": "string",
  • "file_id": "string",
  • "display_name": "string",
  • "sort_order": 0,
  • "link_url": "string",
  • "image_url": "string",
  • "emoji": "string",
  • "type": "link",
  • "original_id": "string",
  • "parent_id": "string",
  • "file": {
    }
}

Update channel bookmark

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

Minimum server version: 9.5

Permissions

Must have the edit_bookmark_public_channel or edit_bookmark_private_channel depending on the channel type. If the channel is a DM or GM, must be a non-guest member.

Authorizations:
bearerAuth
path Parameters
channel_id
required
string

Channel GUID

bookmark_id
required
string

Bookmark GUID

Request Body schema: application/json

Channel Bookmark object to be updated

file_id
string

The ID of the file associated with the channel bookmark. Required for bookmarks of type 'file'

display_name
string

The name of the channel bookmark

sort_order
integer <int64>

The order of the channel bookmark

link_url
string

The URL associated with the channel bookmark. Required for type bookmarks of type 'link'

image_url
string

The URL of the image associated with the channel bookmark

emoji
string

The emoji of the channel bookmark

type
string
Enum: "link" "file"
  • link for channel bookmarks that reference a link. link_url is requied
  • file for channel bookmarks that reference a file. file_id is required

Responses

Request samples

Content type
application/json
{
  • "file_id": "string",
  • "display_name": "string",
  • "sort_order": 0,
  • "link_url": "string",
  • "image_url": "string",
  • "emoji": "string",
  • "type": "link"
}

Response samples

Content type
application/json
{
  • "updated": {
    },
  • "deleted": {
    }
}

Delete channel bookmark

Archives a channel bookmark. This will set the deleteAt to the current timestamp in the database.

Minimum server version: 9.5

Permissions

Must have the delete_bookmark_public_channel or delete_bookmark_private_channel depending on the channel type. If the channel is a DM or GM, must be a non-guest member.

Authorizations:
bearerAuth
path Parameters
channel_id
required
string

Channel GUID

bookmark_id
required
string

Bookmark GUID

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "channel_id": "string",
  • "owner_id": "string",
  • "file_id": "string",
  • "display_name": "string",
  • "sort_order": 0,
  • "link_url": "string",
  • "image_url": "string",
  • "emoji": "string",
  • "type": "link",
  • "original_id": "string",
  • "parent_id": "string",
  • "file": {
    }
}

Update channel bookmark's order

Updates the order of a channel bookmark, setting its new order from the parameters and updating the rest of the bookmarks of the channel to accomodate for this change.

Minimum server version: 9.5

Permissions

Must have the order_bookmark_public_channel or order_bookmark_private_channel depending on the channel type. If the channel is a DM or GM, must be a non-guest member.

Authorizations:
bearerAuth
path Parameters
channel_id
required
string

Channel GUID

bookmark_id
required
string

Bookmark GUID

Request Body schema: application/json
number <int64>

The new sort order for the Channel Bookmark

Responses

Request samples

Content type
application/json
0
0

Response samples

Content type
application/json
[
  • {
    }
]

preferences

Endpoints for saving and modifying user preferences.

Get the user's preferences

Get a list of the user's preferences.

Permissions

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

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Save the user's preferences

Save a list of the user's preferences.

Permissions

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

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

Request Body schema: application/json

List of preference objects

Array ([ 1 .. 100 ] items)
user_id
string

The ID of the user that owns this preference

category
string
name
string
value
string

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "status": "string"
}

Delete user's preferences

Delete a list of the user's preferences.

Permissions

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

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

Request Body schema: application/json

List of preference objects

Array ([ 1 .. 100 ] items)
user_id
string

The ID of the user that owns this preference

category
string
name
string
value
string

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "status": "string"
}

List a user's preferences by category

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

Permissions

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

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

category
required
string

The category of a group of preferences

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a specific user preference

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

Permissions

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

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

category
required
string

The category of a group of preferences

preference_name
required
string

The name of the preference

Responses

Response samples

Content type
application/json
{
  • "user_id": "string",
  • "category": "string",
  • "name": "string",
  • "value": "string"
}

status

Endpoints for getting and updating user statuses.

Get user status

Get user status by id from the server.

Permissions

Must be authenticated.

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User ID

Responses

Response samples

Content type
application/json
{
  • "user_id": "string",
  • "status": "string",
  • "manual": true,
  • "last_activity_at": 0
}

Update user status

Manually set a user's status. When setting a user's status, the status will remain that value until set "online" again, which will return the status to being automatically updated based on user activity.

Permissions

Must have edit_other_users permission for the team.

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User ID

Request Body schema: application/json

Status object that is to be updated

user_id
required
string

User ID

status
required
string

User status, can be online, away, offline and dnd

dnd_end_time
integer

Time in epoch seconds at which a dnd status would be unset.

Responses

Request samples

Content type
application/json
{
  • "user_id": "string",
  • "status": "string",
  • "dnd_end_time": 0
}

Response samples

Content type
application/json
{
  • "user_id": "string",
  • "status": "string",
  • "manual": true,
  • "last_activity_at": 0
}

Get user statuses by id

Get a list of user statuses by id from the server.

Permissions

Must be authenticated.

Authorizations:
bearerAuth
Request Body schema: application/json

List of user ids to fetch

Array
string

Responses

Request samples

Content type
application/json
[
  • "string"
]

Response samples

Content type
application/json
[
  • {
    }
]

Update user custom status

Updates a user's custom status by setting the value in the user's props and updates the user. Also save the given custom status to the recent custom statuses in the user's props

Permissions

Must be logged in as the user whose custom status is being updated.

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User ID

Request Body schema: application/json

Custom status object that is to be updated

emoji
required
string

Any emoji

text
required
string

Any custom status text

duration
string

Duration of custom status, can be thirty_minutes, one_hour, four_hours, today, this_week or date_and_time

expires_at
string

The time at which custom status should be expired. It should be in ISO format.

Responses

Request samples

Content type
application/json
{
  • "emoji": "string",
  • "text": "string",
  • "duration": "string",
  • "expires_at": "string"
}

Response samples

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

Unsets user custom status

Unsets a user's custom status by updating the user's props and updates the user

Permissions

Must be logged in as the user whose custom status is being removed.

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User ID

Responses

Response samples

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

Delete user's recent custom status

Deletes a user's recent custom status by removing the specific status from the recentCustomStatuses in the user's props and updates the user.

Permissions

Must be logged in as the user whose recent custom status is being deleted.

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User ID

Request Body schema: application/json

Custom Status object that is to be removed from the recent custom statuses.

emoji
required
string

Any emoji

text
required
string

Any custom status text

duration
required
string

Duration of custom status, can be thirty_minutes, one_hour, four_hours, today, this_week or date_and_time

expires_at
required
string

The time at which custom status should be expired. It should be in ISO format.

Responses

Request samples

Content type
application/json
{
  • "emoji": "string",
  • "text": "string",
  • "duration": "string",
  • "expires_at": "string"
}

Response samples

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

Delete user's recent custom status

Deletes a user's recent custom status by removing the specific status from the recentCustomStatuses in the user's props and updates the user.

Permissions

Must be logged in as the user whose recent custom status is being deleted.

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User ID

Request Body schema: application/json

Custom Status object that is to be removed from the recent custom statuses.

emoji
required
string

Any emoji

text
required
string

Any custom status text

duration
required
string

Duration of custom status, can be thirty_minutes, one_hour, four_hours, today, this_week or date_and_time

expires_at
required
string

The time at which custom status should be expired. It should be in ISO format.

Responses

Request samples

Content type
application/json
{
  • "emoji": "string",
  • "text": "string",
  • "duration": "string",
  • "expires_at": "string"
}

Response samples

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

emoji

Endpoints for creating, getting and interacting with emojis.

Create a custom emoji

Create a custom emoji for the team.

Permissions

Must be authenticated.

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

A file to be uploaded

emoji
required
string

A JSON object containing a name field with the name of the emoji and a creator_id field with the id of the authenticated user.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "creator_id": "string",
  • "name": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0
}

Get a list of custom emoji

Get a page of metadata for custom emoji on the system. Since server version 4.7, sort using the sort query parameter.

Permissions

Must be authenticated.

Authorizations:
bearerAuth
query Parameters
page
integer
Default: 0

The page to select.

per_page
integer
Default: 60

The number of emojis per page.

sort
string
Default: ""

Either blank for no sorting or "name" to sort by emoji names. Minimum server version for sorting is 4.7.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "creator_id": "string",
  • "name": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0
}

Get a custom emoji

Get some metadata for a custom emoji.

Permissions

Must be authenticated.

Authorizations:
bearerAuth
path Parameters
emoji_id
required
string

Emoji GUID

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "creator_id": "string",
  • "name": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0
}

Delete a custom emoji

Delete a custom emoji.

Permissions

Must have the manage_team or manage_system permissions or be the user who created the emoji.

Authorizations:
bearerAuth
path Parameters
emoji_id
required
string

Emoji GUID

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "creator_id": "string",
  • "name": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0
}

Get a custom emoji by name

Get some metadata for a custom emoji using its name.

Permissions

Must be authenticated.

Minimum server version: 4.7

Authorizations:
bearerAuth
path Parameters
emoji_name
required
string

Emoji name

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "creator_id": "string",
  • "name": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0
}

Get custom emoji image

Get the image for a custom emoji.

Permissions

Must be authenticated.

Authorizations:
bearerAuth
path Parameters
emoji_id
required
string

Emoji GUID

Responses

Response samples

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

Search custom emoji

Search for custom emoji by name based on search criteria provided in the request body. A maximum of 200 results are returned.

Permissions

Must be authenticated.

Minimum server version: 4.7

Authorizations:
bearerAuth
Request Body schema: application/json

Search criteria

term
required
string

The term to match against the emoji name.

prefix_only
string

Set to only search for names starting with the search term.

Responses

Request samples

Content type
application/json
{
  • "term": "string",
  • "prefix_only": "string"
}

Response samples

Content type
application/json
[
  • {
    }
]

Autocomplete custom emoji

Get a list of custom emoji with names starting with or matching the provided name. Returns a maximum of 100 results.

Permissions

Must be authenticated.

Minimum server version: 4.7

Authorizations:
bearerAuth
query Parameters
name
required
string

The emoji name to search.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "creator_id": "string",
  • "name": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0
}

Get custom emojis by name

Get a list of custom emoji based on a provided list of emoji names. A maximum of 200 results are returned.

Permissions

Must be authenticated. Minimum server version: 9.2

Authorizations:
bearerAuth
Request Body schema: application/json

List of emoji names

Array
string

Responses

Request samples

Content type
application/json
[
  • "string"
]

Response samples

Content type
application/json
[
  • {
    }
]

reactions

Endpoints for creating, getting and removing emoji reactions.

Create a reaction

Create a reaction.

Permissions

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

Authorizations:
bearerAuth
Request Body schema: application/json

The user's reaction with its post_id, user_id, and emoji_name fields set

user_id
string

The ID of the user that made this reaction

post_id
string

The ID of the post to which this reaction was made

emoji_name
string

The name of the emoji that was used for this reaction

create_at
integer <int64>

The time in milliseconds this reaction was made

Responses

Request samples

Content type
application/json
{
  • "user_id": "string",
  • "post_id": "string",
  • "emoji_name": "string",
  • "create_at": 0
}

Response samples

Content type
application/json
{
  • "user_id": "string",
  • "post_id": "string",
  • "emoji_name": "string",
  • "create_at": 0
}

Get a list of reactions to a post

Get a list of reactions made by all users to a given post.

Permissions

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

Authorizations:
bearerAuth
path Parameters
post_id
required
string

ID of a post

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Remove a reaction from a post

Deletes a reaction made by a user from the given post.

Permissions

Must be user or have manage_system permission.

Authorizations:
bearerAuth
path Parameters
user_id
required
string

ID of the user

post_id
required
string

ID of the post

emoji_name
required
string

emoji name

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Bulk get the reaction for posts

Get a list of reactions made by all users to a given post.

Permissions

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

Minimum server version: 5.8

Authorizations:
bearerAuth
Request Body schema: application/json

Array of post IDs

Array
string

Responses

Request samples

Content type
application/json
[
  • "string"
]

Response samples

Content type
application/json
{
  • "property1": [
    ],
  • "property2": [
    ]
}

webhooks

Endpoints for creating, getting and updating webhooks.

Create an incoming webhook

Create an incoming webhook for a channel.

Permissions

manage_webhooks for the team the webhook is in.

manage_others_incoming_webhooks for the team the webhook is in if the user is different than the requester.

Authorizations:
bearerAuth
Request Body schema: application/json

Incoming webhook to be created

channel_id
required
string

The ID of a public channel or private group that receives the webhook payloads.

user_id
string

The ID of the owner of the webhook if different than the requester. Required for local mode.

display_name
string

The display name for this incoming webhook

description
string

The description for this incoming webhook

username
string

The username this incoming webhook will post as.

icon_url
string

The profile picture this incoming webhook will use when posting.

Responses

Request samples

Content type
application/json
{
  • "channel_id": "string",
  • "user_id": "string",
  • "display_name": "string",
  • "description": "string",
  • "username": "string",
  • "icon_url": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "channel_id": "string",
  • "description": "string",
  • "display_name": "string"
}

List incoming webhooks

Get a page of a list of incoming webhooks. Optionally filter for a specific team using query parameters.

Permissions

manage_webhooks for the system or manage_webhooks for the specific team.

Authorizations:
bearerAuth
query Parameters
page
integer
Default: 0

The page to select.

per_page
integer
Default: 60

The number of hooks per page.

team_id
string

The ID of the team to get hooks for.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get an incoming webhook

Get an incoming webhook given the hook id.

Permissions

manage_webhooks for system or manage_webhooks for the specific team or manage_webhooks for the channel.

Authorizations:
bearerAuth
path Parameters
hook_id
required
string

Incoming Webhook GUID

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "channel_id": "string",
  • "description": "string",
  • "display_name": "string"
}

Delete an incoming webhook

Delete an incoming webhook given the hook id.

Permissions

manage_webhooks for system or manage_webhooks for the specific team or manage_webhooks for the channel.

Authorizations:
bearerAuth
path Parameters
hook_id
required
string

Incoming webhook GUID

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Update an incoming webhook

Update an incoming webhook given the hook id.

Permissions

manage_webhooks for system or manage_webhooks for the specific team or manage_webhooks for the channel.

Authorizations:
bearerAuth
path Parameters
hook_id
required
string

Incoming Webhook GUID

Request Body schema: application/json

Incoming webhook to be updated

id
required
string

Incoming webhook GUID

channel_id
required
string

The ID of a public channel or private group that receives the webhook payloads.

display_name
required
string

The display name for this incoming webhook

description
required
string

The description for this incoming webhook

username
string

The username this incoming webhook will post as.

icon_url
string

The profile picture this incoming webhook will use when posting.

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "channel_id": "string",
  • "display_name": "string",
  • "description": "string",
  • "username": "string",
  • "icon_url": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "channel_id": "string",
  • "description": "string",
  • "display_name": "string"
}

Create an outgoing webhook

Create an outgoing webhook for a team.

Permissions

manage_webhooks for the team the webhook is in.

manage_others_outgoing_webhooks for the team the webhook is in if the user is different than the requester.

Authorizations:
bearerAuth
Request Body schema: application/json

Outgoing webhook to be created

team_id
required
string

The ID of the team that the webhook watchs

channel_id
string

The ID of a public channel that the webhook watchs

creator_id
string

The ID of the owner of the webhook if different than the requester. Required in local mode.

description
string

The description for this outgoing webhook

display_name
required
string

The display name for this outgoing webhook

trigger_words
required
Array of strings

List of words for the webhook to trigger on

trigger_when
integer

When to trigger the webhook, 0 when a trigger word is present at all and 1 if the message starts with a trigger word

callback_urls
required
Array of strings

The URLs to POST the payloads to when the webhook is triggered

content_type
string
Default: "application/x-www-form-urlencoded"

The format to POST the data in, either application/json or application/x-www-form-urlencoded

Responses

Request samples

Content type
application/json
{
  • "team_id": "string",
  • "channel_id": "string",
  • "creator_id": "string",
  • "description": "string",
  • "display_name": "string",
  • "trigger_words": [
    ],
  • "trigger_when": 0,
  • "callback_urls": [
    ],
  • "content_type": "application/x-www-form-urlencoded"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "creator_id": "string",
  • "team_id": "string",
  • "channel_id": "string",
  • "description": "string",
  • "display_name": "string",
  • "trigger_words": [
    ],
  • "trigger_when": 0,
  • "callback_urls": [
    ],
  • "content_type": "application/x-www-form-urlencoded"
}

List outgoing webhooks

Get a page of a list of outgoing webhooks. Optionally filter for a specific team or channel using query parameters.

Permissions

manage_webhooks for the system or manage_webhooks for the specific team/channel.

Authorizations:
bearerAuth
query Parameters
page
integer
Default: 0

The page to select.

per_page
integer
Default: 60

The number of hooks per page.

team_id
string

The ID of the team to get hooks for.

channel_id
string

The ID of the channel to get hooks for.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get an outgoing webhook

Get an outgoing webhook given the hook id.

Permissions

manage_webhooks for system or manage_webhooks for the specific team or manage_webhooks for the channel.

Authorizations:
bearerAuth
path Parameters
hook_id
required
string

Outgoing webhook GUID

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "creator_id": "string",
  • "team_id": "string",
  • "channel_id": "string",
  • "description": "string",
  • "display_name": "string",
  • "trigger_words": [
    ],
  • "trigger_when": 0,
  • "callback_urls": [
    ],
  • "content_type": "application/x-www-form-urlencoded"
}

Delete an outgoing webhook

Delete an outgoing webhook given the hook id.

Permissions

manage_webhooks for system or manage_webhooks for the specific team or manage_webhooks for the channel.

Authorizations:
bearerAuth
path Parameters
hook_id
required
string

Outgoing webhook GUID

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Update an outgoing webhook

Update an outgoing webhook given the hook id.

Permissions

manage_webhooks for system or manage_webhooks for the specific team or manage_webhooks for the channel.

Authorizations:
bearerAuth
path Parameters
hook_id
required
string

outgoing Webhook GUID

Request Body schema: application/json

Outgoing webhook to be updated

id
required
string

Outgoing webhook GUID

channel_id
required
string

The ID of a public channel or private group that receives the webhook payloads.

display_name
required
string

The display name for this incoming webhook

description
required
string

The description for this incoming webhook

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "channel_id": "string",
  • "display_name": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "creator_id": "string",
  • "team_id": "string",
  • "channel_id": "string",
  • "description": "string",
  • "display_name": "string",
  • "trigger_words": [
    ],
  • "trigger_when": 0,
  • "callback_urls": [
    ],
  • "content_type": "application/x-www-form-urlencoded"
}

Regenerate the token for the outgoing webhook.

Regenerate the token for the outgoing webhook.

Permissions

manage_webhooks for system or manage_webhooks for the specific team or manage_webhooks for the channel.

Authorizations:
bearerAuth
path Parameters
hook_id
required
string

Outgoing webhook GUID

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

commands

Endpoints for creating, getting and updating slash commands.

Create a command

Create a command for a team.

Permissions

manage_slash_commands for the team the command is in.

Authorizations:
bearerAuth
Request Body schema: application/json

command to be created

team_id
required
string

Team ID to where the command should be created

method
required
string

'P' for post request, 'G' for get request

trigger
required
string

Activation word to trigger the command

url
required
string

The URL that the command will make the request

Responses

Request samples

Content type
application/json
{
  • "team_id": "string",
  • "method": "string",
  • "trigger": "string",
  • "url": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "token": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "creator_id": "string",
  • "team_id": "string",
  • "trigger": "string",
  • "method": "string",
  • "username": "string",
  • "icon_url": "string",
  • "auto_complete": true,
  • "auto_complete_desc": "string",
  • "auto_complete_hint": "string",
  • "display_name": "string",
  • "description": "string",
  • "url": "string"
}

List commands for a team

List commands for a team.

Permissions

manage_slash_commands if need list custom commands.

Authorizations:
bearerAuth
query Parameters
team_id
string

The team id.

custom_only
boolean
Default: false

To get only the custom commands. If set to false will get the custom if the user have access plus the system commands, otherwise just the system commands.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List autocomplete commands

List autocomplete commands in the team.

Permissions

view_team for the team.

Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List commands' autocomplete data

List commands' autocomplete data for the team.

Permissions

view_team for the team. Minimum server version: 5.24

Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

query Parameters
user_input
required
string

String inputted by the user.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a command

Get a command definition based on command id string.

Permissions

Must have manage_slash_commands permission for the team the command is in.

Minimum server version: 5.22

Authorizations:
bearerAuth
path Parameters
command_id
required
string

ID of the command to get

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "token": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "creator_id": "string",
  • "team_id": "string",
  • "trigger": "string",
  • "method": "string",
  • "username": "string",
  • "icon_url": "string",
  • "auto_complete": true,
  • "auto_complete_desc": "string",
  • "auto_complete_hint": "string",
  • "display_name": "string",
  • "description": "string",
  • "url": "string"
}

Update a command

Update a single command based on command id string and Command struct.

Permissions

Must have manage_slash_commands permission for the team the command is in.

Authorizations:
bearerAuth
path Parameters
command_id
required
string

ID of the command to update

Request Body schema: application/json
id
string

The ID of the slash command

token
string

The token which is used to verify the source of the payload

create_at
integer

The time in milliseconds the command was created

update_at
integer <int64>

The time in milliseconds the command was last updated

delete_at
integer <int64>

The time in milliseconds the command was deleted, 0 if never deleted

creator_id
string

The user id for the commands creator

team_id
string

The team id for which this command is configured

trigger
string

The string that triggers this command

method
string

Is the trigger done with HTTP Get ('G') or HTTP Post ('P')

username
string

What is the username for the response post

icon_url
string

The url to find the icon for this users avatar

auto_complete
boolean

Use auto complete for this command

auto_complete_desc
string

The description for this command shown when selecting the command

auto_complete_hint
string

The hint for this command

display_name
string

Display name for the command

description
string

Description for this command

url
string

The URL that is triggered

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "token": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "creator_id": "string",
  • "team_id": "string",
  • "trigger": "string",
  • "method": "string",
  • "username": "string",
  • "icon_url": "string",
  • "auto_complete": true,
  • "auto_complete_desc": "string",
  • "auto_complete_hint": "string",
  • "display_name": "string",
  • "description": "string",
  • "url": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "token": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "creator_id": "string",
  • "team_id": "string",
  • "trigger": "string",
  • "method": "string",
  • "username": "string",
  • "icon_url": "string",
  • "auto_complete": true,
  • "auto_complete_desc": "string",
  • "auto_complete_hint": "string",
  • "display_name": "string",
  • "description": "string",
  • "url": "string"
}

Delete a command

Delete a command based on command id string.

Permissions

Must have manage_slash_commands permission for the team the command is in.

Authorizations:
bearerAuth
path Parameters
command_id
required
string

ID of the command to delete

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Move a command

Move a command to a different team based on command id string.

Permissions

Must have manage_slash_commands permission for the team the command is currently in and the destination team.

Minimum server version: 5.22

Authorizations:
bearerAuth
path Parameters
command_id
required
string

ID of the command to move

Request Body schema: application/json
team_id
string

Destination teamId

Responses

Request samples

Content type
application/json
{
  • "team_id": "string"
}

Response samples

Content type
application/json
{
  • "status": "string"
}

Generate a new token

Generate a new token for the command based on command id string.

Permissions

Must have manage_slash_commands permission for the team the command is in.

Authorizations:
bearerAuth
path Parameters
command_id
required
string

ID of the command to generate the new token

Responses

Response samples

Content type
application/json
{
  • "token": "string"
}

Execute a command

Execute a command on a team.

Permissions

Must have use_slash_commands permission for the team the command is in.

Authorizations:
bearerAuth
Request Body schema: application/json

command to be executed

channel_id
required
string

Channel Id where the command will execute

command
required
string

The slash command to execute, including parameters. Eg, '/echo bounces around the room'

Responses

Request samples

Content type
application/json
{
  • "channel_id": "string",
  • "command": "string"
}

Response samples

Content type
application/json
{
  • "ResponseType": "string",
  • "Text": "string",
  • "Username": "string",
  • "IconURL": "string",
  • "GotoLocation": "string",
  • "Attachments": [
    ]
}

system

General endpoints for interacting with the server, such as configuration and logging.

Retrieve a list of supported timezones

Minimum server version: 3.10

Permissions

Must be logged in.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • "string"
]

Check system health

Check if the server is up and healthy based on the configuration setting GoRoutineHealthThreshold. If GoRoutineHealthThreshold and the number of goroutines on the server exceeds that threshold the server is considered unhealthy. If GoRoutineHealthThreshold is not set or the number of goroutines is below the threshold the server is considered healthy. Minimum server version: 3.10 If a "device_id" is passed in the query, it will test the Push Notification Proxy in order to discover whether the device is able to receive notifications. The response will have a "CanReceiveNotifications" property with one of the following values: - true: It can receive notifications - false: It cannot receive notifications - unknown: There has been an unknown error, and it is not certain whether it can

receive notifications.

Minimum server version: 6.5 If "use_rest_semantics" is set to true in the query, the endpoint will not return an error status code in the header if the request is somehow completed successfully. Minimum server version: 9.6

Permissions

None.

Authorizations:
bearerAuth
query Parameters
get_server_status
boolean

Check the status of the database and file storage as well

device_id
string

Check whether this device id can receive push notifications

use_rest_semantics
boolean

Returns 200 status code even if the server status is unhealthy.

Responses

Response samples

Content type
application/json
{
  • "AndroidLatestVersion": "string",
  • "AndroidMinVersion": "string",
  • "DesktopLatestVersion": "string",
  • "DesktopMinVersion": "string",
  • "IosLatestVersion": "string",
  • "IosMinVersion": "string",
  • "database_status": "string",
  • "filestore_status": "string",
  • "status": "string",
  • "CanReceiveNotifications": "string"
}

Get notices for logged in user in specified team

Will return appropriate product notices for current user in the team specified by teamId parameter. Minimum server version: 5.26

Permissions

Must be logged in.

Authorizations:
bearerAuth
path Parameters
teamId
required
string

ID of the team

query Parameters
clientVersion
required
string

Version of the client (desktop/mobile/web) that issues the request

locale
string

Client locale

client
required
string

Client type (web/mobile-ios/mobile-android/desktop)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update notices as 'viewed'

Will mark the specified notices as 'viewed' by the logged in user. Minimum server version: 5.26

Permissions

Must be logged in.

Authorizations:
bearerAuth
Request Body schema: application/json

Array of notice IDs

Array
string

Responses

Request samples

Content type
application/json
[
  • "string"
]

Response samples

Content type
application/json
{
  • "status": "string"
}

Recycle database connections

Recycle database connections by closing and reconnecting all connections to master and read replica databases.

Permissions

Must have manage_system permission.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Send a test email

Send a test email to make sure you have your email settings configured correctly. Optionally provide a configuration in the request body to test. If no valid configuration is present in the request body the current server configuration will be tested.

Permissions

Must have manage_system permission.

Authorizations:
bearerAuth
Request Body schema: application/json

Mattermost configuration

object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object

Responses

Request samples

Content type
application/json
{
  • "ServiceSettings": {
    },
  • "TeamSettings": {
    },
  • "SqlSettings": {
    },
  • "LogSettings": {
    },
  • "PasswordSettings": {
    },
  • "FileSettings": {
    },
  • "EmailSettings": {
    },
  • "RateLimitSettings": {
    },
  • "PrivacySettings": {
    },
  • "SupportSettings": {
    },
  • "GitLabSettings": {
    },
  • "GoogleSettings": {
    },
  • "Office365Settings": {
    },
  • "LdapSettings": {
    },
  • "ComplianceSettings": {
    },
  • "LocalizationSettings": {
    },
  • "SamlSettings": {
    },
  • "NativeAppSettings": {
    },
  • "ClusterSettings": {
    },
  • "MetricsSettings": {
    },
  • "AnalyticsSettings": {
    }
}

Response samples

Content type
application/json
{
  • "status": "string"
}

Checks the validity of a Site URL

Sends a Ping request to the mattermost server using the specified Site URL.

Permissions

Must have manage_system permission.

Minimum server version: 5.16

Authorizations:
bearerAuth
Request Body schema: application/json
site_url
required
string

The Site URL to test

Responses

Request samples

Content type
application/json
{
  • "site_url": "string"
}

Response samples

Content type
application/json
{
  • "status": "string"
}

Test AWS S3 connection

Send a test to validate if can connect to AWS S3. Optionally provide a configuration in the request body to test. If no valid configuration is present in the request body the current server configuration will be tested.

Permissions

Must have manage_system permission. Minimum server version: 4.8

Authorizations:
bearerAuth
Request Body schema: application/json

Mattermost configuration

object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object

Responses

Request samples

Content type
application/json
{
  • "ServiceSettings": {
    },
  • "TeamSettings": {
    },
  • "SqlSettings": {
    },
  • "LogSettings": {
    },
  • "PasswordSettings": {
    },
  • "FileSettings": {
    },
  • "EmailSettings": {
    },
  • "RateLimitSettings": {
    },
  • "PrivacySettings": {
    },
  • "SupportSettings": {
    },
  • "GitLabSettings": {
    },
  • "GoogleSettings": {
    },
  • "Office365Settings": {
    },
  • "LdapSettings": {
    },
  • "ComplianceSettings": {
    },
  • "LocalizationSettings": {
    },
  • "SamlSettings": {
    },
  • "NativeAppSettings": {
    },
  • "ClusterSettings": {
    },
  • "MetricsSettings": {
    },
  • "AnalyticsSettings": {
    }
}

Response samples

Content type
application/json
{
  • "status": "string"
}

Get configuration

Retrieve the current server configuration

Permissions

Must have manage_system permission.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "ServiceSettings": {
    },
  • "TeamSettings": {
    },
  • "SqlSettings": {
    },
  • "LogSettings": {
    },
  • "PasswordSettings": {
    },
  • "FileSettings": {
    },
  • "EmailSettings": {
    },
  • "RateLimitSettings": {
    },
  • "PrivacySettings": {
    },
  • "SupportSettings": {
    },
  • "GitLabSettings": {
    },
  • "GoogleSettings": {
    },
  • "Office365Settings": {
    },
  • "LdapSettings": {
    },
  • "ComplianceSettings": {
    },
  • "LocalizationSettings": {
    },
  • "SamlSettings": {
    },
  • "NativeAppSettings": {
    },
  • "ClusterSettings": {
    },
  • "MetricsSettings": {
    },
  • "AnalyticsSettings": {
    }
}

Update configuration

Submit a new configuration for the server to use. As of server version 4.8, the PluginSettings.EnableUploads setting cannot be modified by this endpoint. Note that the parameters that aren't set in the configuration that you provide will be reset to default values. Therefore, if you want to change a configuration parameter and leave the other ones unchanged, you need to get the existing configuration first, change the field that you want, then put that new configuration.

Permissions

Must have manage_system permission.

Authorizations:
bearerAuth
Request Body schema: application/json

Mattermost configuration

object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object

Responses

Request samples

Content type
application/json
{
  • "ServiceSettings": {
    },
  • "TeamSettings": {
    },
  • "SqlSettings": {
    },
  • "LogSettings": {
    },
  • "PasswordSettings": {
    },
  • "FileSettings": {
    },
  • "EmailSettings": {
    },
  • "RateLimitSettings": {
    },
  • "PrivacySettings": {
    },
  • "SupportSettings": {
    },
  • "GitLabSettings": {
    },
  • "GoogleSettings": {
    },
  • "Office365Settings": {
    },
  • "LdapSettings": {
    },
  • "ComplianceSettings": {
    },
  • "LocalizationSettings": {
    },
  • "SamlSettings": {
    },
  • "NativeAppSettings": {
    },
  • "ClusterSettings": {
    },
  • "MetricsSettings": {
    },
  • "AnalyticsSettings": {
    }
}

Response samples

Content type
application/json
{
  • "ServiceSettings": {
    },
  • "TeamSettings": {
    },
  • "SqlSettings": {
    },
  • "LogSettings": {
    },
  • "PasswordSettings": {
    },
  • "FileSettings": {
    },
  • "EmailSettings": {
    },
  • "RateLimitSettings": {
    },
  • "PrivacySettings": {
    },
  • "SupportSettings": {
    },
  • "GitLabSettings": {
    },
  • "GoogleSettings": {
    },
  • "Office365Settings": {
    },
  • "LdapSettings": {
    },
  • "ComplianceSettings": {
    },
  • "LocalizationSettings": {
    },
  • "SamlSettings": {
    },
  • "NativeAppSettings": {
    },
  • "ClusterSettings": {
    },
  • "MetricsSettings": {
    },
  • "AnalyticsSettings": {
    }
}

Reload configuration

Reload the configuration file to pick up on any changes made to it.

Permissions

Must have manage_system permission.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Get client configuration

Get a subset of the server configuration needed by the client.

Permissions

No permission required.

Authorizations:
bearerAuth
query Parameters
format
required
string

Must be old, other formats not implemented yet

Responses

Response samples

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

Get configuration made through environment variables

Retrieve a json object mirroring the server configuration where fields are set to true if the corresponding config setting is set through an environment variable. Settings that haven't been set through environment variables will be missing from the object.

Minimum server version: 4.10

Permissions

Must have manage_system permission.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "ServiceSettings": {
    },
  • "TeamSettings": {
    },
  • "SqlSettings": {
    },
  • "LogSettings": {
    },
  • "PasswordSettings": {
    },
  • "FileSettings": {
    },
  • "EmailSettings": {
    },
  • "RateLimitSettings": {
    },
  • "PrivacySettings": {
    },
  • "SupportSettings": {
    },
  • "GitLabSettings": {
    },
  • "GoogleSettings": {
    },
  • "Office365Settings": {
    },
  • "LdapSettings": {
    },
  • "ComplianceSettings": {
    },
  • "LocalizationSettings": {
    },
  • "SamlSettings": {
    },
  • "NativeAppSettings": {
    },
  • "ClusterSettings": {
    },
  • "MetricsSettings": {
    },
  • "AnalyticsSettings": {
    }
}

Patch configuration

Submit configuration to patch. As of server version 4.8, the PluginSettings.EnableUploads setting cannot be modified by this endpoint.

Permissions

Must have manage_system permission. Minimum server version: 5.20

Note

The Plugins are stored as a map, and since a map may recursively go down to any depth, individual fields of a map are not changed. Consider using the update config (PUT api/v4/config) endpoint to update a plugins configurations.

Authorizations:
bearerAuth
Request Body schema: application/json

Mattermost configuration

object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object

Responses

Request samples

Content type
application/json
{
  • "ServiceSettings": {
    },
  • "TeamSettings": {
    },
  • "SqlSettings": {
    },
  • "LogSettings": {
    },
  • "PasswordSettings": {
    },
  • "FileSettings": {
    },
  • "EmailSettings": {
    },
  • "RateLimitSettings": {
    },
  • "PrivacySettings": {
    },
  • "SupportSettings": {
    },
  • "GitLabSettings": {
    },
  • "GoogleSettings": {
    },
  • "Office365Settings": {
    },
  • "LdapSettings": {
    },
  • "ComplianceSettings": {
    },
  • "LocalizationSettings": {
    },
  • "SamlSettings": {
    },
  • "NativeAppSettings": {
    },
  • "ClusterSettings": {
    },
  • "MetricsSettings": {
    },
  • "AnalyticsSettings": {
    }
}

Response samples

Content type
application/json
{
  • "ServiceSettings": {
    },
  • "TeamSettings": {
    },
  • "SqlSettings": {
    },
  • "LogSettings": {
    },
  • "PasswordSettings": {
    },
  • "FileSettings": {
    },
  • "EmailSettings": {
    },
  • "RateLimitSettings": {
    },
  • "PrivacySettings": {
    },
  • "SupportSettings": {
    },
  • "GitLabSettings": {
    },
  • "GoogleSettings": {
    },
  • "Office365Settings": {
    },
  • "LdapSettings": {
    },
  • "ComplianceSettings": {
    },
  • "LocalizationSettings": {
    },
  • "SamlSettings": {
    },
  • "NativeAppSettings": {
    },
  • "ClusterSettings": {
    },
  • "MetricsSettings": {
    },
  • "AnalyticsSettings": {
    }
}

Upload license file

Upload a license to enable enterprise features.

Minimum server version: 4.0

Permissions

Must have manage_system permission.

Authorizations:
bearerAuth
Request Body schema: multipart/form-data
license
required
string <binary>

The license to be uploaded

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Remove license file

Remove the license file from the server. This will disable all enterprise features.

Minimum server version: 4.0

Permissions

Must have manage_system permission.

Authorizations:
bearerAuth

Responses

Response samples

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

Get client license

Get a subset of the server license needed by the client.

Permissions

No permission required but having the manage_system permission returns more information.

Authorizations:
bearerAuth
query Parameters
format
required
string

Must be old, other formats not implemented yet

Responses

Response samples

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

Request and install a trial license for your server

Request and install a trial license for your server Minimum server version: 5.25

Permissions

Must have manage_system permission.

Authorizations:
bearerAuth
Request Body schema: application/json

License request

users
required
integer

Number of users requested (20% extra is going to be added)

Responses

Request samples

Content type
application/json
{
  • "users": 0
}

Response samples

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

Get last trial license used

Get the last trial license used on the sevrer Minimum server version: 5.36

Permissions

Must have manage_systems permissions.

Authorizations:
bearerAuth

Responses

Response samples

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

Get audits

Get a page of audits for all users on the system, selected with page and per_page query parameters.

Permissions

Must have manage_system permission.

Authorizations:
bearerAuth
query Parameters
page
integer
Default: 0

The page to select.

per_page
integer
Default: 60

The number of audits per page.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Invalidate all the caches

Purge all the in-memory caches for the Mattermost server. This can have a temporary negative effect on performance while the caches are re-populated.

Permissions

Must have manage_system permission.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Get logs

Get a page of server logs, selected with page and logs_per_page query parameters.

Permissions

Must have manage_system permission.

Authorizations:
bearerAuth
query Parameters
page
integer
Default: 0

The page to select.

logs_per_page
string
Default: "10000"

The number of logs per page. There is a maximum limit of 10000 logs per page.

Responses

Response samples

Content type
application/json
[
  • "string"
]

Add log message

Add log messages to the server logs.

Permissions

Users with manage_system permission can log ERROR or DEBUG messages. Logged in users can log ERROR or DEBUG messages when ServiceSettings.EnableDeveloper is true or just DEBUG messages when false. Non-logged in users can log ERROR or DEBUG messages when ServiceSettings.EnableDeveloper is true and cannot log when false.

Authorizations:
bearerAuth
Request Body schema: application/json
level
required
string

The error level, ERROR or DEBUG

message
required
string

Message to send to the server logs

Responses

Request samples

Content type
application/json
{
  • "level": "string",
  • "message": "string"
}

Response samples

Content type
application/json
{ }

Get analytics

Get some analytics data about the system. This endpoint uses the old format, the /analytics route is reserved for the new format when it gets implemented.

The returned JSON changes based on the name query parameter but is always key/value pairs.

Minimum server version: 4.0

Permissions

Must have manage_system permission.

Authorizations:
bearerAuth
query Parameters
name
string
Default: "standard"

Possible values are "standard", "bot_post_counts_day", "post_counts_day", "user_counts_with_posts_day" or "extra_counts"

team_id
string

The team ID to filter the data by

Responses

Response samples

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

Set the server busy (high load) flag

Marks the server as currently having high load which disables non-critical services such as search, statuses and typing notifications.

Minimum server version: 5.20

Permissions

Must have manage_system permission.

Authorizations:
bearerAuth
query Parameters
seconds
string
Default: "3600"

Number of seconds until server is automatically marked as not busy.

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Get server busy expiry time.

Gets the timestamp corresponding to when the server busy flag will be automatically cleared.

Minimum server version: 5.20

Permissions

Must have manage_system permission.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "busy": true,
  • "expires": 0
}

Clears the server busy (high load) flag

Marks the server as not having high load which re-enables non-critical services such as search, statuses and typing notifications.

Minimum server version: 5.20

Permissions

Must have manage_system permission.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Get redirect location

Minimum server version: 3.10

Permissions

Must be logged in.

Authorizations:
bearerAuth
query Parameters
url
required
string

Url to check

Responses

Response samples

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

Get an image by url

Fetches an image via Mattermost image proxy. Minimum server version: 3.10

Permissions

Must be logged in.

Authorizations:
bearerAuth

Responses

Response samples

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

Executes an inplace upgrade from Team Edition to Enterprise Edition

It downloads the Mattermost Enterprise Edition of your current version and replace your current version with it. After the upgrade you need to restart the Mattermost server. Minimum server version: 5.27

Permissions

Must have manage_system permission.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "ack_id": "string",
  • "platform": "string",
  • "server_id": "string",
  • "device_id": "string",
  • "post_id": "string",
  • "category": "string",
  • "sound": "string",
  • "message": "string",
  • "badge": 0,
  • "cont_ava": 0,
  • "team_id": "string",
  • "channel_id": "string",
  • "root_id": "string",
  • "channel_name": "string",
  • "type": "string",
  • "sender_id": "string",
  • "sender_name": "string",
  • "override_username": "string",
  • "override_icon_url": "string",
  • "from_webhook": "string",
  • "version": "string",
  • "is_id_loaded": true
}

Get the current status for the inplace upgrade from Team Edition to Enterprise Edition

It returns the percentage of completion of the current upgrade or the error if there is any. Minimum server version: 5.27

Permissions

Must have manage_system permission.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "percentage": 0,
  • "error": "string"
}

Restart the system after an upgrade from Team Edition to Enterprise Edition

It restarts the current running mattermost instance to execute the new Enterprise binary. Minimum server version: 5.27

Permissions

Must have manage_system permission.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Perform a database integrity check

Performs a database integrity check.

Note: This check may temporarily harm system performance.

Minimum server version: 5.28.0

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

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Download a zip file which contains helpful and useful information for troubleshooting your mattermost instance.

Download a zip file which contains helpful and useful information for troubleshooting your mattermost instance. Minimum server version: 5.32

Permissions

Must have any of the system console read permissions.

License

Requires either a E10 or E20 license.

Authorizations:
bearerAuth

Responses

Response samples

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

Stores that the Plugin Marketplace has been visited by at least an admin.

Stores the system-level status that specifies that at least an admin has visited the in-product Plugin Marketplace. Minimum server version: 5.33

Permissions

Must have manage_system permissions.

Authorizations:
bearerAuth
Request Body schema: application/json
name
string

System property name

value
string

System property value

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "value": "string"
}

Response samples

Content type
application/json
{
  • "status": "string"
}

brand

Endpoints related to custom branding and white-labeling. See our branding documentation for more information.

Get brand image

Get the previously uploaded brand image. Returns 404 if no brand image has been uploaded.

Permissions

No permission required.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
"string"

Upload brand image

Uploads a brand image.

Permissions

Must have manage_system permission.

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

The image to be uploaded

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Delete current brand image

Deletes the previously uploaded brand image. Returns 404 if no brand image has been uploaded.

Permissions

Must have manage_system permission. Minimum server version: 5.6

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

OAuth

Endpoints for configuring and interacting with Mattermost as an OAuth 2.0 service provider.

Register OAuth app

Register an OAuth 2.0 client application with Mattermost as the service provider.

Permissions

Must have manage_oauth permission.

Authorizations:
bearerAuth
Request Body schema: application/json

OAuth application to register

name
required
string

The name of the client application

description
required
string

A short description of the application

icon_url
string

A URL to an icon to display with the application

callback_urls
required
Array of strings

A list of callback URLs for the appliation

homepage
required
string

A link to the website of the application

is_trusted
boolean

Set this to true to skip asking users for permission

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "icon_url": "string",
  • "callback_urls": [
    ],
  • "homepage": "string",
  • "is_trusted": true
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "client_secret": "string",
  • "name": "string",
  • "description": "string",
  • "icon_url": "string",
  • "callback_urls": [
    ],
  • "homepage": "string",
  • "is_trusted": true,
  • "create_at": 0,
  • "update_at": 0
}

Get OAuth apps

Get a page of OAuth 2.0 client applications registered with Mattermost.

Permissions

With manage_oauth permission, the apps registered by the logged in user are returned. With manage_system_wide_oauth permission, all apps regardless of creator are returned.

Authorizations:
bearerAuth
query Parameters
page
integer
Default: 0

The page to select.

per_page
integer
Default: 60

The number of apps per page.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get an OAuth app

Get an OAuth 2.0 client application registered with Mattermost.

Permissions

If app creator, must have mange_oauth permission otherwise manage_system_wide_oauth permission is required.

Authorizations:
bearerAuth
path Parameters
app_id
required
string

Application client id

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "client_secret": "string",
  • "name": "string",
  • "description": "string",
  • "icon_url": "string",
  • "callback_urls": [
    ],
  • "homepage": "string",
  • "is_trusted": true,
  • "create_at": 0,
  • "update_at": 0
}

Update an OAuth app

Update an OAuth 2.0 client application based on OAuth struct.

Permissions

If app creator, must have mange_oauth permission otherwise manage_system_wide_oauth permission is required.

Authorizations:
bearerAuth
path Parameters
app_id
required
string

Application client id

Request Body schema: application/json

OAuth application to update

id
required
string

The id of the client application

name
required
string

The name of the client application

description
required
string

A short description of the application

icon_url
string

A URL to an icon to display with the application

callback_urls
required
Array of strings

A list of callback URLs for the appliation

homepage
required
string

A link to the website of the application

is_trusted
boolean

Set this to true to skip asking users for permission. It will be set to false if value is not provided.

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "icon_url": "string",
  • "callback_urls": [
    ],
  • "homepage": "string",
  • "is_trusted": true
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "client_secret": "string",
  • "name": "string",
  • "description": "string",
  • "icon_url": "string",
  • "callback_urls": [
    ],
  • "homepage": "string",
  • "is_trusted": true,
  • "create_at": 0,
  • "update_at": 0
}

Delete an OAuth app

Delete and unregister an OAuth 2.0 client application

Permissions

If app creator, must have mange_oauth permission otherwise manage_system_wide_oauth permission is required.

Authorizations:
bearerAuth
path Parameters
app_id
required
string

Application client id

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Regenerate OAuth app secret

Regenerate the client secret for an OAuth 2.0 client application registered with Mattermost.

Permissions

If app creator, must have mange_oauth permission otherwise manage_system_wide_oauth permission is required.

Authorizations:
bearerAuth
path Parameters
app_id
required
string

Application client id

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "client_secret": "string",
  • "name": "string",
  • "description": "string",
  • "icon_url": "string",
  • "callback_urls": [
    ],
  • "homepage": "string",
  • "is_trusted": true,
  • "create_at": 0,
  • "update_at": 0
}

Get info on an OAuth app

Get public information about an OAuth 2.0 client application registered with Mattermost. The application's client secret will be blanked out.

Permissions

Must be authenticated.

Authorizations:
bearerAuth
path Parameters
app_id
required
string

Application client id

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "client_secret": "string",
  • "name": "string",
  • "description": "string",
  • "icon_url": "string",
  • "callback_urls": [
    ],
  • "homepage": "string",
  • "is_trusted": true,
  • "create_at": 0,
  • "update_at": 0
}

Get authorized OAuth apps

Get a page of OAuth 2.0 client applications authorized to access a user's account.

Permissions

Must be authenticated as the user or have edit_other_users permission.

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

query Parameters
page
integer
Default: 0

The page to select.

per_page
integer
Default: 60

The number of apps per page.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

SAML

Endpoints for configuring and interacting with SAML.

Migrate user accounts authentication type to SAML.

Migrates accounts from one authentication provider to another. For example, you can upgrade your authentication provider from email to SAML. Minimum server version: 5.28

Permissions

Must have manage_system permission.

Authorizations:
bearerAuth
Request Body schema: application/json
from
required
string

The current authentication type for the matched users.

matches
required
object

Users map.

auto
required
boolean

Responses

Request samples

Content type
application/json
{
  • "from": "string",
  • "matches": { },
  • "auto": true
}

Response samples

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

Get metadata

Get SAML metadata from the server. SAML must be configured properly.

Permissions

No permission required.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
"string"

Get metadata from Identity Provider

Get SAML metadata from the Identity Provider. SAML must be configured properly.

Permissions

No permission required.

Authorizations:
bearerAuth
Request Body schema: application/json
saml_metadata_url
string

The URL from which to retrieve the SAML IDP data.

Responses

Request samples

Content type
application/json
{
  • "saml_metadata_url": "string"
}

Response samples

Content type
application/json
"string"

Upload IDP certificate

Upload the IDP certificate to be used with your SAML configuration. The server will pick a hard-coded filename for the IdpCertificateFile setting in your config.json.

Permissions

Must have sysconsole_write_authentication permission.

Authorizations:
bearerAuth
Request Body schema: multipart/form-data
certificate
required
string <binary>

The IDP certificate file

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Remove IDP certificate

Delete the current IDP certificate being used with your SAML configuration. This will also disable SAML on your system as this certificate is required for SAML.

Permissions

Must have sysconsole_write_authentication permission.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Upload public certificate

Upload the public certificate to be used for encryption with your SAML configuration. The server will pick a hard-coded filename for the PublicCertificateFile setting in your config.json.

Permissions

Must have sysconsole_write_authentication permission.

Authorizations:
bearerAuth
Request Body schema: multipart/form-data
certificate
required
string <binary>

The public certificate file

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Remove public certificate

Delete the current public certificate being used with your SAML configuration. This will also disable encryption for SAML on your system as this certificate is required for that.

Permissions

Must have sysconsole_write_authentication permission.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Upload private key

Upload the private key to be used for encryption with your SAML configuration. The server will pick a hard-coded filename for the PrivateKeyFile setting in your config.json.

Permissions

Must have sysconsole_write_authentication permission.

Authorizations:
bearerAuth
Request Body schema: multipart/form-data
certificate
required
string <binary>

The private key file

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Remove private key

Delete the current private key being used with your SAML configuration. This will also disable encryption for SAML on your system as this key is required for that.

Permissions

Must have sysconsole_write_authentication permission.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Get certificate status

Get the status of the uploaded certificates and keys in use by your SAML configuration.

Permissions

Must have sysconsole_write_authentication permission.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "idp_certificate_file": true,
  • "public_certificate_file": true,
  • "private_key_file": true
}

Reset AuthData to Email

Reset the AuthData field of SAML users to their email. This is meant to be used when the "id" attribute is set to an empty value ("") from a previously non-empty value. Minimum server version: 5.35

Permissions

Must have manage_system permission.

Authorizations:
bearerAuth
Request Body schema: application/json
include_deleted
boolean
Default: false

Whether to include deleted users.

dry_run
boolean
Default: false

If set to true, the number of users who would be affected is returned.

user_ids
Array of strings
Default: []

If set to a non-empty array, then users whose IDs are not in the array will be excluded.

Responses

Request samples

Content type
application/json
{
  • "include_deleted": false,
  • "dry_run": false,
  • "user_ids": [ ]
}

Response samples

Content type
application/json
{
  • "num_affected": 0
}

LDAP

Endpoints for configuring and interacting with LDAP.

Migrate user accounts authentication type to LDAP.

Migrates accounts from one authentication provider to another. For example, you can upgrade your authentication provider from email to LDAP. Minimum server version: 5.28

Permissions

Must have manage_system permission.

Authorizations:
bearerAuth
Request Body schema: application/json
from
required
string

The current authentication type for the matched users.

match_field
required
string

Foreign user field name to match.

force
required
boolean

Responses

Request samples

Content type
application/json
{
  • "from": "string",
  • "match_field": "string",
  • "force": true
}

Response samples

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

Sync with LDAP

Synchronize any user attribute changes in the configured AD/LDAP server with Mattermost.

Permissions

Must have manage_system permission.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Test LDAP configuration

Test the current AD/LDAP configuration to see if the AD/LDAP server can be contacted successfully.

Permissions

Must have manage_system permission.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Migrate Id LDAP

Migrate LDAP IdAttribute to new value.

Permissions

Must have manage_system permission. Minimum server version: 5.26

Authorizations:
bearerAuth
Request Body schema: application/json
toAttribute
required
string

New IdAttribute value

Responses

Request samples

Content type
application/json
{
  • "toAttribute": "string"
}

Response samples

Content type
application/json
{
  • "status": "string"
}

Upload public certificate

Upload the public certificate to be used for TLS verification. The server will pick a hard-coded filename for the PublicCertificateFile setting in your config.json.

Permissions

Must have manage_system permission.

Authorizations:
bearerAuth
Request Body schema: multipart/form-data
certificate
required
string <binary>

The public certificate file

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Remove public certificate

Delete the current public certificate being used for TLS verification.

Permissions

Must have manage_system permission.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Upload private key

Upload the private key to be used for TLS verification. The server will pick a hard-coded filename for the PrivateKeyFile setting in your config.json.

Permissions

Must have manage_system permission.

Authorizations:
bearerAuth
Request Body schema: multipart/form-data
certificate
required
string <binary>

The private key file

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Remove private key

Delete the current private key being used with your TLS verification.

Permissions

Must have manage_system permission.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Create memberships for LDAP configured channels and teams for this user

Add the user to each channel and team configured for each LDAP group of whicht the user is a member.

Permissions

Must have sysconsole_write_user_management_groups permission.

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User Id

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

groups

Endpoints related to LDAP groups.

Delete a link for LDAP group

Permissions

Must have manage_system permission. Minimum server version: 5.11

Authorizations:
bearerAuth
path Parameters
remote_id
required
string

Group GUID

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Get groups

Retrieve a list of all groups not associated to a particular channel or team.

not_associated_to_team OR not_associated_to_channel is required.

If you use not_associated_to_team, you must be a team admin for that particular team (permission to manage that team).

If you use not_associated_to_channel, you must be a channel admin for that particular channel (permission to manage that channel).

Minimum server version: 5.11

Authorizations:
bearerAuth
query Parameters
page
integer
Default: 0

The page to select.

per_page
integer
Default: 60

The number of groups per page.

q
string

String to pattern match the name and display_name field. Will return all groups whose name and display_name field match any of the text.

include_member_count
boolean

Boolean which adds the member_count attribute to each group JSON object

not_associated_to_team
required
string

Team GUID which is used to return all the groups not associated to this team

not_associated_to_channel
required
string

Group GUID which is used to return all the groups not associated to this channel

since
integer

Only return groups that have been modified since the given Unix timestamp (in milliseconds). All modified groups, including deleted and created groups, will be returned. Minimum server version: 5.24

filter_allow_reference
boolean
Default: false

Boolean which filters the group entries with the allow_reference attribute set.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a custom group

Create a custom type group.

Permission

Must have create_custom_group permission.

Minimum server version: 6.3

Authorizations:
bearerAuth
Request Body schema: application/json

Group object and initial members.

required
object

Group object to create.

user_ids
required
Array of strings

The user ids of the group members to add.

Responses

Request samples

Content type
application/json
{
  • "group": {
    },
  • "user_ids": [
    ]
}

Response samples

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

Get a group

Get group from the provided group id string

Permissions

Must have manage_system permission.

Minimum server version: 5.11

Authorizations:
bearerAuth
path Parameters
group_id
required
string

Group GUID

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "display_name": "string",
  • "description": "string",
  • "source": "string",
  • "remote_id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "has_syncables": true
}

Deletes a custom group

Soft deletes a custom group.

Permissions

Must have custom_group_delete permission for the given group.

Minimum server version: 6.3

Authorizations:
bearerAuth
path Parameters
group_id
required
string

The ID of the group.

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Patch a group

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

Permissions

Must have manage_system permission.

Minimum server version: 5.11

Authorizations:
bearerAuth
path Parameters
group_id
required
string

Group GUID

Request Body schema: application/json

Group object that is to be updated

name
string
display_name
string
description
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "display_name": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "display_name": "string",
  • "description": "string",
  • "source": "string",
  • "remote_id": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "has_syncables": true
}

Restore a previously deleted group.

Restores a previously deleted custom group, allowing it to be used normally. May not be used with LDAP groups.

Permissions Must have restore_custom_group permission for the given group.

Minimum server version: 7.7

Authorizations:
bearerAuth
path Parameters
group_id
required
string

Group GUID

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Link a team to a group

Link a team to a group

Permissions

Must have manage_team permission.

Minimum server version: 5.11

Authorizations:
bearerAuth
path Parameters
group_id
required
string

Group GUID

team_id
required
string

Team GUID

Responses

Response samples

Content type
application/json
{
  • "team_id": "string",
  • "group_id": "string",
  • "auto_add": true,
  • "create_at": 0,
  • "delete_at": 0,
  • "update_at": 0
}

Delete a link from a team to a group

Delete a link from a team to a group

Permissions

Must have manage_team permission.

Minimum server version: 5.11

Authorizations:
bearerAuth
path Parameters
group_id
required
string

Group GUID

team_id
required
string

Team GUID

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Link a channel to a group

Link a channel to a group

Permissions

If the channel is private, you must have manage_private_channel_members permission. Otherwise, you must have the manage_public_channel_members permission.

Minimum server version: 5.11

Authorizations:
bearerAuth
path Parameters
group_id
required
string

Group GUID

channel_id
required
string

Channel GUID

Responses

Response samples

Content type
application/json
{
  • "channel_id": "string",
  • "group_id": "string",
  • "auto_add": true,
  • "create_at": 0,
  • "delete_at": 0,
  • "update_at": 0
}

Delete a link from a channel to a group

Delete a link from a channel to a group

Permissions

If the channel is private, you must have manage_private_channel_members permission. Otherwise, you must have the manage_public_channel_members permission.

Minimum server version: 5.11

Authorizations:
bearerAuth
path Parameters
group_id
required
string

Group GUID

channel_id
required
string

Channel GUID

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Get GroupSyncable from Team ID

Get the GroupSyncable object with group_id and team_id from params

Permissions

Must have manage_system permission.

Minimum server version: 5.11

Authorizations:
bearerAuth
path Parameters
group_id
required
string

Group GUID

team_id
required
string

Team GUID

Responses

Response samples

Content type
application/json
{
  • "team_id": "string",
  • "group_id": "string",
  • "auto_add": true,
  • "create_at": 0,
  • "delete_at": 0,
  • "update_at": 0
}

Get GroupSyncable from channel ID

Get the GroupSyncable object with group_id and channel_id from params

Permissions

Must have manage_system permission.

Minimum server version: 5.11

Authorizations:
bearerAuth
path Parameters
group_id
required
string

Group GUID

channel_id
required
string

Channel GUID

Responses

Response samples

Content type
application/json
{
  • "channel_id": "string",
  • "group_id": "string",
  • "auto_add": true,
  • "create_at": 0,
  • "delete_at": 0,
  • "update_at": 0
}

Get group teams

Retrieve the list of teams associated to the group

Permissions

Must have manage_system permission.

Minimum server version: 5.11

Authorizations:
bearerAuth
path Parameters
group_id
required
string

Group GUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get group channels

Retrieve the list of channels associated to the group

Permissions

Must have manage_system permission.

Minimum server version: 5.11

Authorizations:
bearerAuth
path Parameters
group_id
required
string

Group GUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Patch a GroupSyncable associated to Team

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

Permissions

Must have manage_system permission.

Minimum server version: 5.11

Authorizations:
bearerAuth
path Parameters
group_id
required
string

Group GUID

team_id
required
string

Team GUID

Request Body schema: application/json

GroupSyncable object that is to be updated

auto_add
boolean

Responses

Request samples

Content type
application/json
{
  • "auto_add": true
}

Response samples

Content type
application/json
{
  • "team_id": "string",
  • "group_id": "string",
  • "auto_add": true,
  • "create_at": 0,
  • "delete_at": 0,
  • "update_at": 0
}

Patch a GroupSyncable associated to Channel

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

Permissions

Must have manage_system permission.

Minimum server version: 5.11

Authorizations:
bearerAuth
path Parameters
group_id
required
string

Group GUID

channel_id
required
string

Channel GUID

Request Body schema: application/json

GroupSyncable object that is to be updated

auto_add
boolean

Responses

Request samples

Content type
application/json
{
  • "auto_add": true
}

Response samples

Content type
application/json
{
  • "channel_id": "string",
  • "group_id": "string",
  • "auto_add": true,
  • "create_at": 0,
  • "delete_at": 0,
  • "update_at": 0
}

Get group users

Retrieve the list of users associated with a given group.

Permissions

Must have manage_system permission.

Minimum server version: 5.11

Authorizations:
bearerAuth
path Parameters
group_id
required
string

Group GUID

query Parameters
page
integer
Default: 0

The page to select.

per_page
integer
Default: 60

The number of groups per page.

Responses

Response samples

Content type
application/json
{
  • "members": [
    ],
  • "total_member_count": 0
}

Removes members from a custom group

Soft deletes a custom group members.

Permissions

Must have custom_group_manage_members permission for the given group.

Minimum server version: 6.3

Authorizations:
bearerAuth
path Parameters
group_id
required
string

The ID of the group to delete.

Request Body schema: application/json
user_ids
Array of strings

Responses

Request samples

Content type
application/json
{
  • "user_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "string"
}

Adds members to a custom group

Adds members to a custom group.

Permissions

Must have custom_group_manage_members permission for the given group.

Minimum server version: 6.3

Authorizations:
bearerAuth
path Parameters
group_id
required
string

The ID of the group.

Request Body schema: application/json
user_ids
Array of strings

Responses

Request samples

Content type
application/json
{
  • "user_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "string"
}

Get group stats

Retrieve the stats of a given group.

Permissions

Must have manage_system permission.

Minimum server version: 5.26

Authorizations:
bearerAuth
path Parameters
group_id
required
string

Group GUID

Responses

Response samples

Content type
application/json
{
  • "group_id": "string",
  • "total_member_count": 0
}

Get channel groups

Retrieve the list of groups associated with a given channel.

Permissions

Must have manage_system permission.

Minimum server version: 5.11

Authorizations:
bearerAuth
path Parameters
channel_id
required
string

Channel GUID

query Parameters
page
integer
Default: 0

The page to select.

per_page
integer
Default: 60

The number of groups per page.

filter_allow_reference
boolean
Default: false

Boolean which filters the group entries with the allow_reference attribute set.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get team groups

Retrieve the list of groups associated with a given team.

Permissions

Must have the list_team_channels permission.

Minimum server version: 5.11

Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

query Parameters
page
integer
Default: 0

The page to select.

per_page
integer
Default: 60

The number of groups per page.

filter_allow_reference
boolean
Default: false

Boolean which filters in the group entries with the allow_reference attribute set.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get team groups by channels

Retrieve the set of groups associated with the channels in the given team grouped by channel.

Permissions

Must have the list_team_channels permission.

Minimum server version: 5.11

Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team GUID

query Parameters
page
integer
Default: 0

The page to select.

per_page
integer
Default: 60

The number of groups per page.

filter_allow_reference
boolean
Default: false

Boolean which filters in the group entries with the allow_reference attribute set.

paginate
boolean
Default: false

Boolean to determine whether the pagination should be applied or not

Responses

Response samples

Content type
application/json
{ }

Get groups for a userId

Retrieve the list of groups associated to the user

Minimum server version: 5.24

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

compliance

Endpoints for creating, getting and downloading compliance reports.

Create report

Create and save a compliance report.

Permissions

Must have manage_system permission.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "create_at": 0,
  • "user_id": "string",
  • "status": "string",
  • "count": 0,
  • "desc": "string",
  • "type": "string",
  • "start_at": 0,
  • "end_at": 0,
  • "keywords": "string",
  • "emails": "string"
}

Get reports

Get a list of compliance reports previously created by page, selected with page and per_page query parameters.

Permissions

Must have manage_system permission.

Authorizations:
bearerAuth
query Parameters
page
integer
Default: 0

The page to select.

per_page
integer
Default: 60

The number of reports per page.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a report

Get a compliance reports previously created.

Permissions

Must have manage_system permission.

Authorizations:
bearerAuth
path Parameters
report_id
required
string

Compliance report GUID

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "create_at": 0,
  • "user_id": "string",
  • "status": "string",
  • "count": 0,
  • "desc": "string",
  • "type": "string",
  • "start_at": 0,
  • "end_at": 0,
  • "keywords": "string",
  • "emails": "string"
}

Download a report

Download the full contents of a report as a file.

Permissions

Must have manage_system permission.

Authorizations:
bearerAuth
path Parameters
report_id
required
string

Compliance report GUID

Responses

Response samples

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

cluster

Endpoints for configuring and interacting with high availability clusters.

Get cluster status

Get a set of information for each node in the cluster, useful for checking the status and health of each node.

Permissions

Must have manage_system permission.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

cloud

Get cloud workspace limits

Retrieve any cloud workspace limits applicable to this instance.

Permissions

Must be authenticated and be licensed for Cloud. Minimum server version: 7.0 Note: This is intended for internal use and is subject to change.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "boards": {
    },
  • "files": {
    },
  • "integrations": {
    },
  • "messages": {
    },
  • "teams": {
    }
}

Get cloud products

Retrieve a list of all products that are offered for Mattermost Cloud.

Permissions

Must have manage_system permission and be licensed for Cloud. Minimum server version: 5.28 Note: This is intended for internal use and is subject to change.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a customer setup payment intent

Creates a customer setup payment intent for the given Mattermost cloud installation.

Permissions

Must have manage_system permission and be licensed for Cloud.

Minimum server version: 5.28 Note:: This is intended for internal use and is subject to change.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "client_secret": "string"
}

Completes the payment setup intent

Confirms the payment setup intent initiated when posting to /cloud/payment.

Permissions

Must have manage_system permission and be licensed for Cloud. Minimum server version: 5.28 Note: This is intended for internal use and is subject to change.

Authorizations:
bearerAuth
Request Body schema: multipart/form-data
stripe_setup_intent_id
string

Responses

Response samples

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

Get cloud customer

Retrieves the customer information for the Mattermost Cloud customer bound to this installation.

Permissions

Must have manage_system permission and be licensed for Cloud. Minimum server version: 5.28 Note: This is intended for internal use and is subject to change.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "creator_id": "string",
  • "create_at": 0,
  • "email": "string",
  • "name": "string",
  • "num_employees": "string",
  • "contact_first_name": "string",
  • "contact_last_name": "string",
  • "billing_address": {
    },
  • "company_address": {
    },
  • "payment_method": {
    }
}

Update cloud customer

Updates the customer information for the Mattermost Cloud customer bound to this installation.

Permissions

Must have manage_system permission and be licensed for Cloud. Minimum server version: 5.29 Note: This is intended for internal use and is subject to change.

Authorizations:
bearerAuth
Request Body schema: application/json

Customer patch including information to update

name
string
email
string
contact_first_name
string
contact_last_name
string
num_employees
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "email": "string",
  • "contact_first_name": "string",
  • "contact_last_name": "string",
  • "num_employees": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "creator_id": "string",
  • "create_at": 0,
  • "email": "string",
  • "name": "string",
  • "num_employees": "string",
  • "contact_first_name": "string",
  • "contact_last_name": "string",
  • "billing_address": {
    },
  • "company_address": {
    },
  • "payment_method": {
    }
}

Update cloud customer address

Updates the company address for the Mattermost Cloud customer bound to this installation.

Permissions

Must have manage_system permission and be licensed for Cloud. Minimum server version: 5.29 Note: This is intended for internal use and is subject to change.

Authorizations:
bearerAuth
Request Body schema: application/json

Company address information to update

city
string
country
string
line1
string
line2
string
postal_code
string
state
string

Responses

Request samples

Content type
application/json
{
  • "city": "string",
  • "country": "string",
  • "line1": "string",
  • "line2": "string",
  • "postal_code": "string",
  • "state": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "creator_id": "string",
  • "create_at": 0,
  • "email": "string",
  • "name": "string",
  • "num_employees": "string",
  • "contact_first_name": "string",
  • "contact_last_name": "string",
  • "billing_address": {
    },
  • "company_address": {
    },
  • "payment_method": {
    }
}

Get cloud subscription

Retrieves the subscription information for the Mattermost Cloud customer bound to this installation.

Permissions

Must have manage_system permission and be licensed for Cloud. Minimum server version: 5.28 Note: This is intended for internal use and is subject to change.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "customer_id": "string",
  • "product_id": "string",
  • "add_ons": [
    ],
  • "start_at": 0,
  • "end_at": 0,
  • "create_at": 0,
  • "seats": 0,
  • "dns": "string"
}

GET endpoint for Installation information

An endpoint for fetching the installation information.

Permissions

Must have sysconsole_read_site_ip_filters permission and be licensed for Cloud. Minimum server version: 9.1 Note: This is intended for internal use and is subject to change.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "allowed_ip_ranges": {
    },
  • "state": "string"
}

Get cloud subscription invoices

Retrieves the invoices for the subscription bound to this installation.

Permissions

Must have manage_system permission and be licensed for Cloud. Minimum server version: 5.30 Note: This is intended for internal use and is subject to change.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get cloud invoice PDF

Retrieves the PDF for the invoice passed as parameter

Permissions

Must have manage_system permission and be licensed for Cloud. Minimum server version: 5.30 Note: This is intended for internal use and is subject to change.

Authorizations:
bearerAuth
path Parameters
invoice_id
required
string

Invoice ID

Responses

Response samples

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

POST endpoint for CWS Webhooks

An endpoint for processing webhooks from the Customer Portal

Permissions

This endpoint should only be accessed by CWS, in a Mattermost Cloud instance Minimum server version: 5.30 Note: This is intended for internal use and is subject to change.

Authorizations:
bearerAuth

Responses

Response samples

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

elasticsearch

Endpoints for configuring and interacting with Elasticsearch.

Test Elasticsearch configuration

Test the current Elasticsearch configuration to see if the Elasticsearch server can be contacted successfully. Optionally provide a configuration in the request body to test. If no valid configuration is present in the request body the current server configuration will be tested.

Minimum server version: 4.1

Permissions

Must have manage_system permission.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Purge all Elasticsearch indexes

Deletes all Elasticsearch indexes and their contents. After calling this endpoint, it is necessary to schedule a new Elasticsearch indexing job to repopulate the indexes. Minimum server version: 4.1

Permissions

Must have manage_system permission.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

bleve

Purge all Bleve indexes

Deletes all Bleve indexes and their contents. After calling this endpoint, it is necessary to schedule a new Bleve indexing job to repopulate the indexes. Minimum server version: 5.24

Permissions

Must have sysconsole_write_experimental permission.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

data retention

Endpoint for getting data retention policy settings.

Get the policies which are applied to a user's teams

Gets the policies which are applied to the all of the teams to which a user belongs.

Minimum server version: 5.35

Permissions

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

License

Requires an E20 license.

Authorizations:
bearerAuth
path Parameters
user_id
required
string

The ID of the user. This can also be "me" which will point to the current user.

query Parameters
page
integer
Default: 0

The page to select.

per_page
integer
Default: 60

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

Responses

Response samples

Content type
application/json
{
  • "policies": [
    ],
  • "total_count": 0
}

Get the policies which are applied to a user's channels

Gets the policies which are applied to the all of the channels to which a user belongs.

Minimum server version: 5.35

Permissions

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

License

Requires an E20 license.

Authorizations:
bearerAuth
path Parameters
user_id
required
string

The ID of the user. This can also be "me" which will point to the current user.

query Parameters
page
integer
Default: 0

The page to select.

per_page
integer
Default: 60

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

Responses

Response samples

Content type
application/json
{
  • "policies": [
    ],
  • "total_count": 0
}

Get the global data retention policy

Gets the current global data retention policy details from the server, including what data should be purged and the cutoff times for each data type that should be purged.

Minimum server version: 4.3

Permissions

Requires an active session but no other permissions.

License

Requires an E20 license.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "message_deletion_enabled": true,
  • "file_deletion_enabled": true,
  • "message_retention_cutoff": 0,
  • "file_retention_cutoff": 0
}

Get the number of granular data retention policies

Gets the number of granular (i.e. team or channel-specific) data retention policies from the server.

Minimum server version: 5.35

Permissions

Must have the sysconsole_read_compliance_data_retention permission.

License

Requires an E20 license.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "total_count": 0
}

Get the granular data retention policies

Gets details about the granular (i.e. team or channel-specific) data retention policies from the server.

Minimum server version: 5.35

Permissions

Must have the sysconsole_read_compliance_data_retention permission.

License

Requires an E20 license.

Authorizations:
bearerAuth
query Parameters
page
integer
Default: 0

The page to select.

per_page
integer
Default: 60

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

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new granular data retention policy

Creates a new granular data retention policy with the specified display name and post duration.

Minimum server version: 5.35

Permissions

Must have the sysconsole_write_compliance_data_retention permission.

License

Requires an E20 license.

Authorizations:
bearerAuth
Request Body schema: application/json
display_name
required
string

The display name for this retention policy.

post_duration
required
integer

The number of days a message will be retained before being deleted by this policy. If this value is less than 0, the policy has infinite retention (i.e. messages are never deleted).

team_ids
Array of strings

The IDs of the teams to which this policy should be applied.

channel_ids
Array of strings

The IDs of the channels to which this policy should be applied.

Responses

Request samples

Content type
application/json
{
  • "display_name": "string",
  • "post_duration": 0,
  • "team_ids": [
    ],
  • "channel_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "display_name": "string",
  • "post_duration": 0,
  • "id": "string",
  • "team_count": 0,
  • "channel_count": 0
}

Get a granular data retention policy

Gets details about a granular data retention policies by ID.

Minimum server version: 5.35

Permissions

Must have the sysconsole_read_compliance_data_retention permission.

License

Requires an E20 license.

Authorizations:
bearerAuth
path Parameters
policy_id
required
string

The ID of the granular retention policy.

Responses

Response samples

Content type
application/json
{
  • "display_name": "string",
  • "post_duration": 0,
  • "id": "string",
  • "team_count": 0,
  • "channel_count": 0
}

Patch a granular data retention policy

Patches (i.e. replaces the fields of) a granular data retention policy. If any fields are omitted, they will not be changed.

Minimum server version: 5.35

Permissions

Must have the sysconsole_write_compliance_data_retention permission.

License

Requires an E20 license.

Authorizations:
bearerAuth
path Parameters
policy_id
required
string

The ID of the granular retention policy.

Request Body schema: application/json
display_name
string

The display name for this retention policy.

post_duration
integer

The number of days a message will be retained before being deleted by this policy. If this value is less than 0, the policy has infinite retention (i.e. messages are never deleted).

team_ids
Array of strings

The IDs of the teams to which this policy should be applied.

channel_ids
Array of strings

The IDs of the channels to which this policy should be applied.

Responses

Request samples

Content type
application/json
{
  • "display_name": "string",
  • "post_duration": 0,
  • "team_ids": [
    ],
  • "channel_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "display_name": "string",
  • "post_duration": 0,
  • "id": "string",
  • "team_count": 0,
  • "channel_count": 0
}

Delete a granular data retention policy

Deletes a granular data retention policy.

Minimum server version: 5.35

Permissions

Must have the sysconsole_write_compliance_data_retention permission.

License

Requires an E20 license.

Authorizations:
bearerAuth
path Parameters
policy_id
required
string

The ID of the granular retention policy.

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Get the teams for a granular data retention policy

Gets the teams to which a granular data retention policy is applied.

Minimum server version: 5.35

Permissions

Must have the sysconsole_read_compliance_data_retention permission.

License

Requires an E20 license.

Authorizations:
bearerAuth
path Parameters
policy_id
required
string

The ID of the granular retention policy.

query Parameters
page
integer
Default: 0

The page to select.

per_page
integer
Default: 60

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

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add teams to a granular data retention policy

Adds teams to a granular data retention policy.

Minimum server version: 5.35

Permissions

Must have the sysconsole_write_compliance_data_retention permission.

License

Requires an E20 license.

Authorizations:
bearerAuth
path Parameters
policy_id
required
string

The ID of the granular retention policy.

Request Body schema: application/json
Array
string

The IDs of the teams to add to the policy.

Responses

Request samples

Content type
application/json
[
  • "string"
]

Response samples

Content type
application/json
{
  • "status": "string"
}

Delete teams from a granular data retention policy

Delete teams from a granular data retention policy.

Minimum server version: 5.35

Permissions

Must have the sysconsole_write_compliance_data_retention permission.

License

Requires an E20 license.

Authorizations:
bearerAuth
path Parameters
policy_id
required
string

The ID of the granular retention policy.

Request Body schema: application/json
Array
string

The IDs of the teams to remove from the policy.

Responses

Request samples

Content type
application/json
[
  • "string"
]

Response samples

Content type
application/json
{
  • "status": "string"
}

Search for the teams in a granular data retention policy

Searches for the teams to which a granular data retention policy is applied.

Minimum server version: 5.35

Permissions

Must have the sysconsole_read_compliance_data_retention permission.

License

Requires an E20 license.

Authorizations:
bearerAuth
path Parameters
policy_id
required
string

The ID of the granular retention policy.

Request Body schema: application/json
term
string

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

Responses

Request samples

Content type
application/json
{
  • "term": "string"
}

Response samples

Content type
application/json
[
  • {
    }
]

Get the channels for a granular data retention policy

Gets the channels to which a granular data retention policy is applied.

Minimum server version: 5.35

Permissions

Must have the sysconsole_read_compliance_data_retention permission.

License

Requires an E20 license.

Authorizations:
bearerAuth
path Parameters
policy_id
required
string

The ID of the granular retention policy.

query Parameters
page
integer
Default: 0

The page to select.

per_page
integer
Default: 60

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

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add channels to a granular data retention policy

Adds channels to a granular data retention policy.

Minimum server version: 5.35

Permissions

Must have the sysconsole_write_compliance_data_retention permission.

License

Requires an E20 license.

Authorizations:
bearerAuth
path Parameters
policy_id
required
string

The ID of the granular retention policy.

Request Body schema: application/json
Array
string

The IDs of the channels to add to the policy.

Responses

Request samples

Content type
application/json
[
  • "string"
]

Response samples

Content type
application/json
{
  • "status": "string"
}

Delete channels from a granular data retention policy

Delete channels from a granular data retention policy.

Minimum server version: 5.35

Permissions

Must have the sysconsole_write_compliance_data_retention permission.

License

Requires an E20 license.

Authorizations:
bearerAuth
path Parameters
policy_id
required
string

The ID of the granular retention policy.

Request Body schema: application/json
Array
string

The IDs of the channels to add to the policy.

Responses

Request samples

Content type
application/json
[
  • "string"
]

Response samples

Content type
application/json
{
  • "status": "string"
}

Search for the channels in a granular data retention policy

Searches for the channels to which a granular data retention policy is applied.

Minimum server version: 5.35

Permissions

Must have the sysconsole_read_compliance_data_retention permission.

License

Requires an E20 license.

Authorizations:
bearerAuth
path Parameters
policy_id
required
string

The ID of the granular retention policy.

Request Body schema: application/json
term
string

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

team_ids
Array of strings

Filters results to channels belonging to the given team ids

public
boolean

Filters results to only return Public / Open channels, can be used in conjunction with private to return both public and private channels

private
boolean

Filters results to only return Private channels, can be used in conjunction with public to return both private and public channels

deleted
boolean

Filters results to only return deleted / archived channels

Responses

Request samples

Content type
application/json
{
  • "term": "string",
  • "team_ids": [
    ],
  • "public": true,
  • "private": true,
  • "deleted": true
}

Response samples

Content type
application/json
[
  • {
    }
]

jobs

Endpoints related to various background jobs that can be run by the server or separately by job servers.

Get the jobs.

Get a page of jobs. Use the query parameters to modify the behaviour of this endpoint. Minimum server version: 4.1

Permissions

Must have manage_jobs permission.

Authorizations:
bearerAuth
query Parameters
page
integer
Default: 0

The page to select.

per_page
integer
Default: 60

The number of jobs per page.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new job.

Create a new job. Minimum server version: 4.1

Permissions

Must have manage_jobs permission.

Authorizations:
bearerAuth
Request Body schema: application/json

Job object to be created

type
required
string

The type of job to create

data
object

An object containing any additional data required for this job type

Responses

Request samples

Content type
application/json
{
  • "type": "string",
  • "data": { }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "string",
  • "create_at": 0,
  • "start_at": 0,
  • "last_activity_at": 0,
  • "status": "string",
  • "progress": 0,
  • "data": { }
}

Get a job.

Gets a single job. Minimum server version: 4.1

Permissions

Must have manage_jobs permission.

Authorizations:
bearerAuth
path Parameters
job_id
required
string

Job GUID

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "string",
  • "create_at": 0,
  • "start_at": 0,
  • "last_activity_at": 0,
  • "status": "string",
  • "progress": 0,
  • "data": { }
}

Download the results of a job.

Download the result of a single job. Minimum server version: 5.28

Permissions

Must have manage_jobs permission.

Authorizations:
bearerAuth
path Parameters
job_id
required
string

Job GUID

Responses

Response samples

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

Cancel a job.

Cancel a job. Minimum server version: 4.1

Permissions

Must have manage_jobs permission.

Authorizations:
bearerAuth
path Parameters
job_id
required
string

Job GUID

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Get the jobs of the given type.

Get a page of jobs of the given type. Use the query parameters to modify the behaviour of this endpoint. Minimum server version: 4.1

Permissions

Must have manage_jobs permission.

Authorizations:
bearerAuth
path Parameters
type
required
string

Job type

query Parameters
page
integer
Default: 0

The page to select.

per_page
integer
Default: 60

The number of jobs per page.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

plugins

Endpoints related to uploading and managing plugins.

Upload plugin

Upload a plugin that is contained within a compressed .tar.gz file. Plugins and plugin uploads must be enabled in the server's config settings.

Permissions

Must have manage_system permission.

Minimum server version: 4.4

Authorizations:
bearerAuth
Request Body schema: multipart/form-data
plugin
required
string <binary>

The plugin image to be uploaded

force
string

Set to 'true' to overwrite a previously installed plugin with the same ID, if any

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Get plugins

Get a list of inactive and a list of active plugin manifests. Plugins must be enabled in the server's config settings.

Permissions

Must have manage_system permission.

Minimum server version: 4.4

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "active": [
    ],
  • "inactive": [
    ]
}

Install plugin from url

Supply a URL to a plugin compressed in a .tar.gz file. Plugins must be enabled in the server's config settings.

Permissions

Must have manage_system permission.

Minimum server version: 5.14

Authorizations:
bearerAuth
query Parameters
plugin_download_url
required
string

URL used to download the plugin

force
string

Set to 'true' to overwrite a previously installed plugin with the same ID, if any

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Remove plugin

Remove the plugin with the provided ID from the server. All plugin files are deleted. Plugins must be enabled in the server's config settings.

Permissions

Must have manage_system permission.

Minimum server version: 4.4

Authorizations:
bearerAuth
path Parameters
plugin_id
required
string

Id of the plugin to be removed

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Enable plugin

Enable a previously uploaded plugin. Plugins must be enabled in the server's config settings.

Permissions

Must have manage_system permission.

Minimum server version: 4.4

Authorizations:
bearerAuth
path Parameters
plugin_id
required
string

Id of the plugin to be enabled

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Disable plugin

Disable a previously enabled plugin. Plugins must be enabled in the server's config settings.

Permissions

Must have manage_system permission.

Minimum server version: 4.4

Authorizations:
bearerAuth
path Parameters
plugin_id
required
string

Id of the plugin to be disabled

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Get webapp plugins

Get a list of web app plugins installed and activated on the server.

Permissions

No permissions required.

Minimum server version: 4.4

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get plugins status

Returns the status for plugins installed anywhere in the cluster

Permissions

No permissions required.

Minimum server version: 4.4

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Installs a marketplace plugin

Installs a plugin listed in the marketplace server.

Permissions

Must have manage_system permission.

Minimum server version: 5.16

Authorizations:
bearerAuth
Request Body schema: application/json

The metadata identifying the plugin to install.

id
required
string

The ID of the plugin to install.

version
required
string

The version of the plugin to install.

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "version": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "version": "string",
  • "min_server_version": "string",
  • "backend": {
    },
  • "server": {
    },
  • "webapp": {
    },
  • "settings_schema": { }
}

Gets all the marketplace plugins

Gets all plugins from the marketplace server, merging data from locally installed plugins as well as prepackaged plugins shipped with the server.

Permissions

Must have manage_system permission.

Minimum server version: 5.16

Authorizations:
bearerAuth
query Parameters
page
integer

Page number to be fetched. (not yet implemented)

per_page
integer

Number of item per page. (not yet implemented)

filter
string

Set to filter plugins by ID, name, or description.

server_version
string

Set to filter minimum plugin server version. (not yet implemented)

local_only
boolean

Set true to only retrieve local plugins.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get if the Plugin Marketplace has been visited by at least an admin.

Retrieves the status that specifies that at least one System Admin has visited the in-product Plugin Marketplace. Minimum server version: 5.33

Permissions

Must have manage_system permissions.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "value": "string"
}

roles

Endpoints for creating, getting and updating roles.

Get a list of all the roles

Permissions

manage_system permission is required.

Minimum server version: 5.33

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a role

Get a role from the provided role id.

Permissions

Requires an active session but no other permissions.

Minimum server version: 4.9

Authorizations:
bearerAuth
path Parameters
role_id
required
string

Role GUID

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "display_name": "string",
  • "description": "string",
  • "permissions": [
    ],
  • "scheme_managed": true
}

Get a role

Get a role from the provided role name.

Permissions

Requires an active session but no other permissions.

Minimum server version: 4.9

Authorizations:
bearerAuth
path Parameters
role_name
required
string

Role Name

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "display_name": "string",
  • "description": "string",
  • "permissions": [
    ],
  • "scheme_managed": true
}

Patch a role

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

Permissions

manage_system permission is required.

Minimum server version: 4.9

Authorizations:
bearerAuth
path Parameters
role_id
required
string

Role GUID

Request Body schema: application/json

Role object to be updated

permissions
Array of strings

The permissions the role should grant.

Responses

Request samples

Content type
application/json
{
  • "permissions": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "display_name": "string",
  • "description": "string",
  • "permissions": [
    ],
  • "scheme_managed": true
}

Get a list of roles by name

Get a list of roles from their names.

Permissions

Requires an active session but no other permissions.

Minimum server version: 4.9

Authorizations:
bearerAuth
Request Body schema: application/json

List of role names

Array
string

Responses

Request samples

Content type
application/json
[
  • "string"
]

Response samples

Content type
application/json
[
  • {
    }
]

schemes

Endpoints for creating, getting and updating and deleting schemes.

Get the schemes.

Get a page of schemes. Use the query parameters to modify the behaviour of this endpoint.

Permissions

Must have manage_system permission.

Minimum server version: 5.0

Authorizations:
bearerAuth
query Parameters
scope
string
Default: ""

Limit the results returned to the provided scope, either team or channel.

page
integer
Default: 0

The page to select.

per_page
integer
Default: 60

The number of schemes per page.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a scheme

Create a new scheme.

Permissions

Must have manage_system permission.

Minimum server version: 5.0

Authorizations:
bearerAuth
Request Body schema: application/json

Scheme object to create

name
required
string

The name of the scheme

description
string

The description of the scheme

scope
required
string

The scope of the scheme ("team" or "channel")

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "scope": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "scope": "string",
  • "default_team_admin_role": "string",
  • "default_team_user_role": "string",
  • "default_channel_admin_role": "string",
  • "default_channel_user_role": "string"
}

Get a scheme

Get a scheme from the provided scheme id.

Permissions

Must have manage_system permission.

Minimum server version: 5.0

Authorizations:
bearerAuth
path Parameters
scheme_id
required
string

Scheme GUID

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "scope": "string",
  • "default_team_admin_role": "string",
  • "default_team_user_role": "string",
  • "default_channel_admin_role": "string",
  • "default_channel_user_role": "string"
}

Delete a scheme

Soft deletes a scheme, by marking the scheme as deleted in the database.

Permissions

Must have manage_system permission.

Minimum server version: 5.0

Authorizations:
bearerAuth
path Parameters
scheme_id
required
string

ID of the scheme to delete

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Patch a scheme

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

Permissions

manage_system permission is required.

Minimum server version: 5.0

Authorizations:
bearerAuth
path Parameters
scheme_id
required
string

Scheme GUID

Request Body schema: application/json

Scheme object to be updated

name
string

The human readable name of the scheme

description
string

The description of the scheme

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "create_at": 0,
  • "update_at": 0,
  • "delete_at": 0,
  • "scope": "string",
  • "default_team_admin_role": "string",
  • "default_team_user_role": "string",
  • "default_channel_admin_role": "string",
  • "default_channel_user_role": "string"
}

Get a page of teams which use this scheme.

Get a page of teams which use this scheme. The provided Scheme ID should be for a Team-scoped Scheme. Use the query parameters to modify the behaviour of this endpoint.

Permissions

manage_system permission is required.

Minimum server version: 5.0

Authorizations:
bearerAuth
path Parameters
scheme_id
required
string

Scheme GUID

query Parameters
page
integer
Default: 0

The page to select.

per_page
integer
Default: 60

The number of teams per page.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a page of channels which use this scheme.

Get a page of channels which use this scheme. The provided Scheme ID should be for a Channel-scoped Scheme. Use the query parameters to modify the behaviour of this endpoint.

Permissions

manage_system permission is required.

Minimum server version: 5.0

Authorizations:
bearerAuth
path Parameters
scheme_id
required
string

Scheme GUID

query Parameters
page
integer
Default: 0

The page to select.

per_page
integer
Default: 60

The number of channels per page.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

integration_actions

Endpoints for interactive actions for use by integrations.

Open a dialog

Open an interactive dialog using a trigger ID provided by a slash command, or some other action payload. See https://docs.mattermost.com/developer/interactive-dialogs.html for more information on interactive dialogs. Minimum server version: 5.6

Authorizations:
bearerAuth
Request Body schema: application/json

Metadata for the dialog to be opened

trigger_id
required
string

Trigger ID provided by other action

url
required
string

The URL to send the submitted dialog payload to

required
object

Post object to create

Responses

Request samples

Content type
application/json
{
  • "trigger_id": "string",
  • "url": "string",
  • "dialog": {
    }
}

Response samples

Content type
application/json
{
  • "status": "string"
}

Submit a dialog

Endpoint used by the Mattermost clients to submit a dialog. See https://docs.mattermost.com/developer/interactive-dialogs.html for more information on interactive dialogs. Minimum server version: 5.6

Authorizations:
bearerAuth
Request Body schema: application/json

Dialog submission data

url
required
string

The URL to send the submitted dialog payload to

channel_id
required
string

Channel ID the user submitted the dialog from

team_id
required
string

Team ID the user submitted the dialog from

submission
required
object

String map where keys are element names and values are the element input values

callback_id
string

Callback ID sent when the dialog was opened

state
string

State sent when the dialog was opened

cancelled
boolean

Set to true if the dialog was cancelled

Responses

Request samples

Content type
application/json
{
  • "url": "string",
  • "channel_id": "string",
  • "team_id": "string",
  • "submission": { },
  • "callback_id": "string",
  • "state": "string",
  • "cancelled": true
}

Response samples

Content type
application/json
{
  • "status": "string"
}

shared channels

Endpoints for getting information about shared channels.

Get all shared channels for team.

Get all shared channels for a team.

Minimum server version: 5.50

Permissions

Must be authenticated.

Authorizations:
bearerAuth
path Parameters
team_id
required
string

Team Id

query Parameters
page
integer
Default: 0

The page to select.

per_page
integer
Default: 0

The number of sharedchannels per page.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get remote cluster info by ID for user.

Get remote cluster info based on remoteId.

Minimum server version: 5.50

Permissions

Must be authenticated and user must belong to at least one channel shared with the remote cluster.

Authorizations:
bearerAuth
path Parameters
remote_id
required
string

Remote Cluster GUID

Responses

Response samples

Content type
application/json
{
  • "display_name": "string",
  • "create_at": 0,
  • "last_ping_at": 0
}

terms of service

Endpoints for getting and updating custom terms of service.

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

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

Minimum server version: 5.4

Permissions

Must be logged in as the user being acted on.

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

Request Body schema: application/json

terms of service details

serviceTermsId
required
string

terms of service ID on which the user is acting on

accepted
required
string

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

Responses

Request samples

Content type
application/json
{
  • "serviceTermsId": "string",
  • "accepted": "string"
}

Response samples

Content type
application/json
{
  • "status": "string"
}

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

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

Minimum server version: 5.6

Permissions

Must be logged in as the user being acted on.

Authorizations:
bearerAuth
path Parameters
user_id
required
string

User GUID

Responses

Response samples

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

Get latest terms of service

Get latest terms of service from the server

Minimum server version: 5.4

Permissions

Must be authenticated.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "create_at": 0,
  • "user_id": "string",
  • "text": "string"
}

Creates a new terms of service

Creates new terms of service

Minimum server version: 5.4

Permissions

Must have manage_system permission.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "create_at": 0,
  • "user_id": "string",
  • "text": "string"
}

imports

Endpoints related to import files.

List import files

Lists all available import files.

Minimum server version: 5.31

Permissions

Must have manage_system permissions.

Authorizations:
bearerAuth

Responses

Response samples

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

permissions

Return all system console subsection ancillary permissions

Returns all the ancillary permissions for the corresponding system console subsection permissions appended to the requested permission subsections.

Minimum server version: 5.35

Authorizations:
bearerAuth
query Parameters
subsection_permissions
string

The subsection permissions to return the ancillary permissions for. These values are comma seperated. Ex. subsection_permissions=sysconsole_read_reporting_site_statistics,sysconsole_write_reporting_site_statistics,sysconsole_write_user_management_channels

Responses

Response samples

Content type
application/json
[
  • "string"
]

exports

Endpoints related to export files.

List export files

Lists all available export files. Minimum server version: 5.33

Permissions

Must have manage_system permissions.

Authorizations:
bearerAuth

Responses

Response samples

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

Download an export file

Downloads an export file.

Minimum server version: 5.33

Permissions

Must have manage_system permissions.

Authorizations:
bearerAuth
path Parameters
export_name
required
string

The name of the export file to download

Responses

Response samples

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

Delete an export file

Deletes an export file.

Minimum server version: 5.33

Permissions

Must have manage_system permissions.

Authorizations:
bearerAuth
path Parameters
export_name
required
string

The name of the export file to delete

Responses

Response samples

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

usage

Get current usage of posts

Retrieve rounded off total no. of posts for this instance. Example: returns 4000 instead of 4321

Permissions

Must be authenticated. Minimum server version: 7.0

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "count": 0
}

Get the total file storage usage for the instance in bytes.

Get the total file storage usage for the instance in bytes rounded down to the most significant digit. Example: returns 4000 instead of 4321

Permissions

Must be authenticated. Minimum server version: 7.1

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "bytes": 0
}

Playbooks

Playbooks

List all playbooks

Retrieve a paged list of playbooks, filtered by team, and sorted by title, number of stages or number of steps.

Authorizations:
BearerAuth
query Parameters
team_id
required
string
Example: team_id=08fmfasq5wit3qyfmq4mjk0rto

ID of the team to filter by.

page
integer <int32>
Default: 0
Example: page=3

Zero-based index of the page to request.

per_page
integer <int32>
Default: 1000
Example: per_page=50

Number of playbooks to return per page.

sort
string
Default: "title"
Enum: "title" "stages" "steps"
Example: sort=stages

Field to sort the returned playbooks by title, number of stages or total number of steps.

direction
string
Default: "asc"
Enum: "desc" "asc"
Example: direction=asc

Direction (ascending or descending) followed by the sorting of the playbooks.

with_archived
boolean
Default: false
Example: with_archived=true

Includes archived playbooks in the result.

Responses

Request samples

curl -X GET 'http://localhost:8065/plugins/playbooks/api/v0/playbooks?team_id=08fmfasq5wit3qyfmq4mjk0rto&sort=title&direction=asc' \
-H 'Authorization: Bearer 9g64ig7q9pds8yjz8rsgd6e36e'

Response samples

Content type
application/json
{
  • "total_count": 305,
  • "page_count": 2,
  • "has_more": true,
  • "items": [
    ]
}

Create a playbook

Authorizations:
BearerAuth
Request Body schema: application/json

Playbook

title
required
string

The title of the playbook.

description
string

The description of the playbook.

team_id
required
string

The identifier of the team where the playbook is in.

create_public_playbook_run
required
boolean

A boolean indicating whether the playbook runs created from this playbook should be public or private.

public
boolean

A boolean indicating whether the playbook is licensed as public or private. Required 'true' for free tier.

required
Array of objects

The stages defined by this playbook.

member_ids
required
Array of strings

The identifiers of all the users that are members of this playbook.

broadcast_channel_ids
Array of strings

The IDs of the channels where all the status updates will be broadcasted. The team of the broadcast channel must be the same as the playbook's team.

invited_user_ids
Array of strings

A list with the IDs of the members to be automatically invited to the playbook run's channel as soon as the playbook run is created.

invite_users_enabled
boolean

Boolean that indicates whether the members declared in invited_user_ids will be automatically invited.

default_owner_id
string

User ID of the member that will be automatically assigned as owner as soon as the playbook run is created. If the member is not part of the playbook run's channel or is not included in the invited_user_ids list, they will be automatically invited to the channel.

default_owner_enabled
string

Boolean that indicates whether the member declared in default_owner_id will be automatically assigned as owner.

announcement_channel_id
string

ID of the channel where the playbook run will be automatically announced as soon as the playbook run is created.

announcement_channel_enabled
boolean

Boolean that indicates whether the playbook run creation will be announced in the channel declared in announcement_channel_id.

webhook_on_creation_url
string

An absolute URL where a POST request will be sent as soon as the playbook run is created. The allowed protocols are HTTP and HTTPS.

webhook_on_creation_enabled
boolean

Boolean that indicates whether the webhook declared in webhook_on_creation_url will be automatically sent.

webhook_on_status_update_url
string

An absolute URL where a POST request will be sent as soon as the playbook run's status is updated. The allowed protocols are HTTP and HTTPS.

webhook_on_status_update_enabled
boolean

Boolean that indicates whether the webhook declared in webhook_on_status_update_url will be automatically sent.

Responses

Callbacks

Request samples

Content type
application/json
{
  • "title": "Cloud PlaybookRuns",
  • "description": "A playbook to follow when there is a playbook run regarding the availability of the cloud service.",
  • "team_id": "p03rbi6viyztysbqnkvcqyel2i",
  • "create_public_playbook_run": true,
  • "public": true,
  • "checklists": [
    ],
  • "member_ids": "ilh6s1j4yefbdhxhtlzt179i6m",
  • "broadcast_channel_ids": "2zh7rpashwfwapwaqyslmhwbax",
  • "invited_user_ids": "01kidjn9iozv7bist427w4gkjo",
  • "invite_users_enabled": true,
  • "default_owner_id": "9dtruav6d9ce3oqnc5pwhtqtfq",
  • "default_owner_enabled": true,
  • "announcement_channel_id": "8iofau5swv32l6qtk3vlxgobta",
  • "announcement_channel_enabled": true,
  • "webhook_on_creation_url": "https://httpbin.org/post",
  • "webhook_on_creation_enabled": true,
  • "webhook_on_status_update_url": "https://httpbin.org/post",
  • "webhook_on_status_update_enabled": true
}

Response samples

Content type
application/json
{
  • "id": "iz0g457ikesz55dhxcfa0fk9yy"
}

Callback payload samples

Callback
Content type
application/json
{
  • "id": "mx3xyzdojfgyfdx8sc8of1gdme",
  • "name": "Server down in EU cluster",
  • "description": "There is one server in the EU cluster that is not responding since April 12.",
  • "is_active": true,
  • "owner_user_id": "bqnbdf8uc0a8yz4i39qrpgkvtg",
  • "team_id": "61ji2mpflefup3cnuif80r5rde",
  • "channel_id": "hwrmiyzj3kadcilh3ukfcnsbt6",
  • "create_at": 1606807976289,
  • "end_at": 0,
  • "delete_at": 0,
  • "active_stage": 1,
  • "active_stage_title": "Triage issue",
  • "post_id": "b2ntfcrl4ujivl456ab4b3aago",
  • "playbook_id": "0y4a0ntte97cxvfont8y84wa7x",
  • "checklists": [
    ],
}

Get a playbook

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: iz0g457ikesz55dhxcfa0fk9yy

ID of the playbook to retrieve.

Responses

Request samples

curl -X GET 'http://localhost:8065/plugins/playbooks/api/v0/playbooks/iz0g457ikesz55dhxcfa0fk9yy' \
-H 'Authorization: Bearer 9g64ig7q9pds8yjz8rsgd6e36e'

Response samples

Content type
application/json
{
  • "id": "iz0g457ikesz55dhxcfa0fk9yy",
  • "title": "Cloud PlaybookRuns",
  • "description": "A playbook to follow when there is a playbook run regarding the availability of the cloud service.",
  • "team_id": "p03rbi6viyztysbqnkvcqyel2i",
  • "create_public_playbook_run": true,
  • "create_at": 1602235338837,
  • "delete_at": 0,
  • "num_stages": 3,
  • "num_steps": 18,
  • "checklists": [
    ],
  • "member_ids": "ilh6s1j4yefbdhxhtlzt179i6m"
}

Update a playbook

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: iz0g457ikesz55dhxcfa0fk9yy

ID of the playbook to update.

Request Body schema: application/json

Playbook payload

id
string

A unique, 26 characters long, alphanumeric identifier for the playbook.

title
string

The title of the playbook.

description
string

The description of the playbook.

team_id
string

The identifier of the team where the playbook is in.

create_public_playbook_run
boolean

A boolean indicating whether the playbook runs created from this playbook should be public or private.

create_at
integer <int64>

The playbook creation timestamp, formatted as the number of milliseconds since the Unix epoch.

delete_at
integer <int64>

The playbook deletion timestamp, formatted as the number of milliseconds since the Unix epoch. It equals 0 if the playbook is not deleted.

num_stages
integer <int64>

The number of stages defined in this playbook.

num_steps
integer <int64>

The total number of steps from all the stages defined in this playbook.

Array of objects (Checklist)

The stages defined in this playbook.

member_ids
Array of strings

The identifiers of all the users that are members of this playbook.

Responses

Request samples

Content type
application/json
{
  • "id": "iz0g457ikesz55dhxcfa0fk9yy",
  • "title": "Cloud PlaybookRuns",
  • "description": "A playbook to follow when there is a playbook run regarding the availability of the cloud service.",
  • "team_id": "p03rbi6viyztysbqnkvcqyel2i",
  • "create_public_playbook_run": true,
  • "create_at": 1602235338837,
  • "delete_at": 0,
  • "num_stages": 3,
  • "num_steps": 18,
  • "checklists": [
    ],
  • "member_ids": "ilh6s1j4yefbdhxhtlzt179i6m"
}

Response samples

Content type
application/json
{
  • "error": "Error retrieving the resource.",
  • "details": "Specific details about the error, depending on the case."
}

Delete a playbook

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: iz0g457ikesz55dhxcfa0fk9yy

ID of the playbook to delete.

Responses

Request samples

curl -X DELETE 'http://localhost:8065/plugins/playbooks/api/v0/playbooks/iz0g457ikesz55dhxcfa0fk9yy' \
-H 'Authorization: Bearer 9g64ig7q9pds8yjz8rsgd6e36e'

Response samples

Content type
application/json
{
  • "error": "Error retrieving the resource.",
  • "details": "Specific details about the error, depending on the case."
}

PlaybookRuns

Playbook runs

List all playbook runs

Retrieve a paged list of playbook runs, filtered by team, status, owner, name and/or members, and sorted by ID, name, status, creation date, end date, team or owner ID.

Authorizations:
BearerAuth
query Parameters
team_id
required
string
Example: team_id=el3d3t9p55pevvxs2qkdwz334k

ID of the team to filter by.

page
integer <int32>
Default: 0
Example: page=3

Zero-based index of the page to request.

per_page
integer <int32>
Default: 1000
Example: per_page=50

Number of playbook runs to return per page.

sort
string
Default: "create_at"
Enum: "id" "name" "is_active" "create_at" "end_at" "team_id" "owner_user_id"
Example: sort=end_at

Field to sort the returned playbook runs by.

direction
string
Default: "desc"
Enum: "desc" "asc"
Example: direction=asc

Direction (ascending or descending) followed by the sorting of the playbook runs.

statuses
Array of strings
Default: ["InProgress"]
Items Enum: "InProgress" "Finished"
Example: statuses=InProgress

The returned list will contain only the playbook runs with the specified statuses.

owner_user_id
string
Example: owner_user_id=lpn2ogt9qzkc59lfvvad9t15v4

The returned list will contain only the playbook runs commanded by this user. Specify "me" for current user.

participant_id
string
Example: participant_id=bruhg1cs65retdbea798hrml4v

The returned list will contain only the playbook runs for which the given user is a participant. Specify "me" for current user.

search_term
string
Example: search_term=server down

The returned list will contain only the playbook runs whose name contains the search term.

Responses

Request samples

curl -X GET 'http://localhost:8065/plugins/playbooks/api/v0/runs' \
-H 'Authorization: Bearer 9g64ig7q9pds8yjz8rsgd6e36e'

Response samples

Content type
application/json
{
  • "total_count": 305,
  • "page_count": 2,
  • "has_more": true,
  • "items": [
    ]
}

Create a new playbook run

Create a new playbook run in a team, using a playbook as template, with a specific name and a specific owner.

Authorizations:
BearerAuth
Request Body schema: application/json

Playbook run payload.

name
required
string

The name of the playbook run.

description
string

The description of the playbook run.

owner_user_id
required
string

The identifier of the user who is commanding the playbook run.

team_id
required
string

The identifier of the team where the playbook run's channel is in.

post_id
string

If the playbook run was created from a post, this field contains the identifier of such post. If not, this field is empty.

playbook_id
required
string

The identifier of the playbook with from which this playbook run was created.

Responses

Request samples

Content type
application/json
{
  • "name": "Server down in EU cluster",
  • "description": "There is one server in the EU cluster that is not responding since April 12.",
  • "owner_user_id": "bqnbdf8uc0a8yz4i39qrpgkvtg",
  • "team_id": "61ji2mpflefup3cnuif80r5rde",
  • "post_id": "b2ntfcrl4ujivl456ab4b3aago",
  • "playbook_id": "0y4a0ntte97cxvfont8y84wa7x"
}

Response samples

Content type
application/json
{
  • "id": "mx3xyzdojfgyfdx8sc8of1gdme",
  • "name": "Server down in EU cluster",
  • "description": "There is one server in the EU cluster that is not responding since April 12.",
  • "is_active": true,
  • "owner_user_id": "bqnbdf8uc0a8yz4i39qrpgkvtg",
  • "team_id": "61ji2mpflefup3cnuif80r5rde",
  • "channel_id": "hwrmiyzj3kadcilh3ukfcnsbt6",
  • "create_at": 1606807976289,
  • "end_at": 0,
  • "delete_at": 0,
  • "active_stage": 1,
  • "active_stage_title": "Triage issue",
  • "post_id": "b2ntfcrl4ujivl456ab4b3aago",
  • "playbook_id": "0y4a0ntte97cxvfont8y84wa7x",
  • "checklists": [
    ]
}

Get all owners

Get the owners of all playbook runs, filtered by team.

Authorizations:
BearerAuth
query Parameters
team_id
required
string
Example: team_id=el3d3t9p55pevvxs2qkdwz334k

ID of the team to filter by.

Responses

Request samples

curl -X GET 'http://localhost:8065/plugins/playbooks/api/v0/runs/owners?team_id=ni8duypfe7bamprxqeffd563gy' \
-H 'Authorization: Bearer 9g64ig7q9pds8yjz8rsgd6e36e'

Response samples

Content type
application/json
[
  • {
    }
]

Get playbook run channels

Get all channels associated with a playbook run, filtered by team, status, owner, name and/or members, and sorted by ID, name, status, creation date, end date, team, or owner ID.

Authorizations:
BearerAuth
query Parameters
team_id
required
string
Example: team_id=el3d3t9p55pevvxs2qkdwz334k

ID of the team to filter by.

sort
string
Default: "create_at"
Enum: "id" "name" "create_at" "end_at" "team_id" "owner_user_id"
Example: sort=end_at

Field to sort the returned channels by, according to their playbook run.

direction
string
Default: "desc"
Enum: "desc" "asc"
Example: direction=asc

Direction (ascending or descending) followed by the sorting of the playbook runs associated to the channels.

status
string
Default: "all"
Enum: "all" "InProgress" "Finished"
Example: status=active

The returned list will contain only the channels whose playbook run has this status.

owner_user_id
string
Example: owner_user_id=lpn2ogt9qzkc59lfvvad9t15v4

The returned list will contain only the channels whose playbook run is commanded by this user.

search_term
string
Example: search_term=server down

The returned list will contain only the channels associated to a playbook run whose name contains the search term.

participant_id
string
Example: participant_id=bruhg1cs65retdbea798hrml4v

The returned list will contain only the channels associated to a playbook run for which the given user is a participant.

Responses

Request samples

curl -X GET 'http://localhost:8065/plugins/playbooks/api/v0/runs/channels?team_id=ni8duypfe7bamprxqeffd563gy' \
-H 'Authorization: Bearer 9g64ig7q9pds8yjz8rsgd6e36e'

Response samples

Content type
application/json
"v8zdc1893plelmf54vb7f0ramn"

Find playbook run by channel ID

Authorizations:
BearerAuth
path Parameters
channel_id
required
string
Example: hwrmiyzj3kadcilh3ukfcnsbt6

ID of the channel associated to the playbook run to retrieve.

Responses

Request samples

curl -X GET 'http://localhost:8065/plugins/playbooks/api/v0/runs/channel/hwrmiyzj3kadcilh3ukfcnsbt6' \
-H 'Authorization: Bearer 9g64ig7q9pds8yjz8rsgd6e36e'

Response samples

Content type
application/json
{
  • "id": "mx3xyzdojfgyfdx8sc8of1gdme",
  • "name": "Server down in EU cluster",
  • "description": "There is one server in the EU cluster that is not responding since April 12.",
  • "is_active": true,
  • "owner_user_id": "bqnbdf8uc0a8yz4i39qrpgkvtg",
  • "team_id": "61ji2mpflefup3cnuif80r5rde",
  • "channel_id": "hwrmiyzj3kadcilh3ukfcnsbt6",
  • "create_at": 1606807976289,
  • "end_at": 0,
  • "delete_at": 0,
  • "active_stage": 1,
  • "active_stage_title": "Triage issue",
  • "post_id": "b2ntfcrl4ujivl456ab4b3aago",
  • "playbook_id": "0y4a0ntte97cxvfont8y84wa7x",
  • "checklists": [
    ]
}

Get a playbook run

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: mx3xyzdojfgyfdx8sc8of1gdme

ID of the playbook run to retrieve.

Responses

Request samples

curl -X GET 'http://localhost:8065/plugins/playbooks/api/v0/runs/mx3xyzdojfgyfdx8sc8of1gdme' \
-H 'Authorization: Bearer 9g64ig7q9pds8yjz8rsgd6e36e'

Response samples

Content type
application/json
{
  • "id": "mx3xyzdojfgyfdx8sc8of1gdme",
  • "name": "Server down in EU cluster",
  • "description": "There is one server in the EU cluster that is not responding since April 12.",
  • "is_active": true,
  • "owner_user_id": "bqnbdf8uc0a8yz4i39qrpgkvtg",
  • "team_id": "61ji2mpflefup3cnuif80r5rde",
  • "channel_id": "hwrmiyzj3kadcilh3ukfcnsbt6",
  • "create_at": 1606807976289,
  • "end_at": 0,
  • "delete_at": 0,
  • "active_stage": 1,
  • "active_stage_title": "Triage issue",
  • "post_id": "b2ntfcrl4ujivl456ab4b3aago",
  • "playbook_id": "0y4a0ntte97cxvfont8y84wa7x",
  • "checklists": [
    ]
}

Update a playbook run

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: mx3xyzdojfgyfdx8sc8of1gdme

ID of the playbook run to retrieve.

Request Body schema: application/json

Playbook run update payload.

active_stage
integer

Zero-based index of the stage that will be made active.

Responses

Request samples

Content type
application/json
{
  • "active_stage": 2
}

Response samples

Content type
application/json
{
  • "error": "Error retrieving the resource.",
  • "details": "Specific details about the error, depending on the case."
}

Get playbook run metadata

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: mx3xyzdojfgyfdx8sc8of1gdme

ID of the playbook run whose metadata will be retrieved.

Responses

Request samples

curl -X GET 'http://localhost:8065/plugins/playbooks/api/v0/runs/1igmynxs77ywmcbwbsujzktter/details' \
-H 'Authorization: Bearer 9g64ig7q9pds8yjz8rsgd6e36e'

Response samples

Content type
application/json
{
  • "channel_name": "server-down-in-eu-cluster",
  • "channel_display_name": "Server down in EU cluster",
  • "team_name": "sre-staff",
  • "num_members": 25,
  • "total_posts": 202
}

End a playbook run

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 1igmynxs77ywmcbwbsujzktter

ID of the playbook run to end.

Responses

Request samples

curl -X PUT 'http://localhost:8065/plugins/playbooks/api/v0/runs/1igmynxs77ywmcbwbsujzktter/end' \
-H 'Authorization: Bearer 9g64ig7q9pds8yjz8rsgd6e36e'

Response samples

Content type
application/json
{
  • "error": "Error retrieving the resource.",
  • "details": "Specific details about the error, depending on the case."
}

Restart a playbook run

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 1igmynxs77ywmcbwbsujzktter

ID of the playbook run to restart.

Responses

Request samples

curl -X PUT 'http://localhost:8065/plugins/playbooks/api/v0/runs/1igmynxs77ywmcbwbsujzktter/end' \
-H 'Authorization: Bearer 9g64ig7q9pds8yjz8rsgd6e36e'

Response samples

Content type
application/json
{
  • "error": "Error retrieving the resource.",
  • "details": "Specific details about the error, depending on the case."
}

Update a playbook run's status

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 1igmynxs77ywmcbwbsujzktter

ID of the playbook run to update.

Request Body schema: application/json

Payload to change the playbook run's status update message.

message
required
string

The status update message.

reminder
number

The number of seconds until the system will send a reminder to the owner to update the status. No reminder will be scheduled if reminder is 0 or omitted.

Responses

Request samples

Content type
application/json
{
  • "message": "Starting to investigate.",
  • "reminder": 600
}

Response samples

Content type
application/json
{
  • "error": "Error retrieving the resource.",
  • "details": "Specific details about the error, depending on the case."
}

Finish a playbook

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 1igmynxs77ywmcbwbsujzktter

ID of the playbook run to finish.

Responses

Request samples

curl -X PUT 'http://localhost:8065/plugins/playbooks/api/v0/runs/1igmynxs77ywmcbwbsujzktter/finish' \
-H 'Authorization: Bearer 9g64ig7q9pds8yjz8rsgd6e36e'

Response samples

Content type
application/json
{
  • "error": "Error retrieving the resource.",
  • "details": "Specific details about the error, depending on the case."
}

Update playbook run owner

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 1igmynxs77ywmcbwbsujzktter

ID of the playbook run whose owner will be changed.

Request Body schema: application/json

Payload to change the playbook run's owner.

owner_id
required
string

The user ID of the new owner.

Responses

Request samples

Content type
application/json
{
  • "owner_id": "hx7fqtqxp7nn8129t7e505ls6s"
}

Response samples

Content type
application/json
{
  • "error": "Error retrieving the resource.",
  • "details": "Specific details about the error, depending on the case."
}

Add an item to a playbook run's checklist

The most common pattern to add a new item is to only send its title as the request payload. By default, it is an open item, with no assignee and no slash command.

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: twcqg0a2m37ydi6ebge3j9ev5z

ID of the playbook run whose checklist will be modified.

checklist
required
integer
Example: 1

Zero-based index of the checklist to modify.

Request Body schema: application/json

Checklist item payload.

title
required
string

The title of the checklist item.

state
string
Enum: "" "in_progress" "closed"

The state of the checklist item. An empty string means that the item is not done.

state_modified
integer <int64>

The timestamp for the latest modification of the item's state, formatted as the number of milliseconds since the Unix epoch. It equals 0 if the item was never modified.

assignee_id
string

The identifier of the user that has been assigned to complete this item. If the item has no assignee, this is an empty string.

assignee_modified
integer <int64>

The timestamp for the latest modification of the item's assignee, formatted as the number of milliseconds since the Unix epoch. It equals 0 if the item never got an assignee.

command
string

The slash command associated with this item. If the item has no slash command associated, this is an empty string

command_last_run
integer <int64>

The timestamp for the latest execution of the item's command, formatted as the number of milliseconds since the Unix epoch. It equals 0 if the command was never executed.

description
string

A detailed description of the checklist item, formatted with Markdown.

Responses

Request samples

Content type
application/json
{
  • "title": "Gather information from customer.",
  • "state": "closed",
  • "state_modified": 1607774621321,
  • "assignee_id": "pisdatkjtdlkdhht2v4inxuzx1",
  • "assignee_modified": 1608897821125,
  • "command": "/opsgenie on-call",
  • "command_last_run": 1608552221019,
  • "description": "Ask the customer for more information in [Zendesk](https://www.zendesk.com/)."
}

Response samples

Content type
application/json
{
  • "error": "Error retrieving the resource.",
  • "details": "Specific details about the error, depending on the case."
}

Reorder an item in a playbook run's checklist

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: yj74zsk7dvtsv6ndsynsps3g5s

ID of the playbook run whose checklist will be modified.

checklist
required
integer
Example: 1

Zero-based index of the checklist to modify.

Request Body schema: application/json

Reorder checklist item payload.

item_num
required
integer

Zero-based index of the item to reorder.

new_location
required
integer

Zero-based index of the new place to move the item to.

Responses

Request samples

Content type
application/json
{
  • "item_num": 2,
  • "new_location": 2
}

Response samples

Content type
application/json
{
  • "error": "Error retrieving the resource.",
  • "details": "Specific details about the error, depending on the case."
}

Update an item of a playbook run's checklist

Update the title and the slash command of an item in one of the playbook run's checklists.

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 6t7jdgyqr7b5sk24zkauhmrb06

ID of the playbook run whose checklist will be modified.

checklist
required
integer
Example: 1

Zero-based index of the checklist to modify.

item
required
integer
Example: 2

Zero-based index of the item to modify.

Request Body schema: application/json

Update checklist item payload.

title
required
string

The new title of the item.

command
required
string

The new slash command of the item.

Responses

Request samples

Content type
application/json
{
  • "title": "Gather information from server's logs.",
  • "command": "/jira update ticket"
}

Response samples

Content type
application/json
{
  • "error": "Error retrieving the resource.",
  • "details": "Specific details about the error, depending on the case."
}

Delete an item of a playbook run's checklist

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: zjy2q2iy2jafl0lo2oddos5xn7

ID of the playbook run whose checklist will be modified.

checklist
required
integer
Example: 1

Zero-based index of the checklist to modify.

item
required
integer
Example: 2

Zero-based index of the item to modify.

Responses

Request samples

curl -X DELETE 'http://localhost:8065/plugins/playbooks/api/v0/runs/zjy2q2iy2jafl0lo2oddos5xn7/checklists/1/item/2' \
-H 'Authorization: Bearer 9g64ig7q9pds8yjz8rsgd6e36e'

Response samples

Content type
application/json
{
  • "error": "Error retrieving the resource.",
  • "details": "Specific details about the error, depending on the case."
}

Update the state of an item

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 7l37isroz4e63giev62hs318bn

ID of the playbook run whose checklist will be modified.

checklist
required
integer
Example: 1

Zero-based index of the checklist to modify.

item
required
integer
Example: 2

Zero-based index of the item to modify.

Request Body schema: application/json

Update checklist item's state payload.

new_state
required
string
Default: ""
Enum: "" "in_progress" "closed"

The new state of the item.

Responses

Request samples

Content type
application/json
{
  • "new_state": "closed"
}

Response samples

Content type
application/json
{
  • "error": "Error retrieving the resource.",
  • "details": "Specific details about the error, depending on the case."
}

Update the assignee of an item

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 7l37isroz4e63giev62hs318bn

ID of the playbook run whose item will get a new assignee.

checklist
required
integer
Example: 1

Zero-based index of the checklist whose item will get a new assignee.

item
required
integer
Example: 2

Zero-based index of the item that will get a new assignee.

Request Body schema: application/json

User ID of the new assignee.

assignee_id
required
string

The user ID of the new assignee of the item.

Responses

Request samples

Content type
application/json
{
  • "assignee_id": "ruu86intseidqdxjojia41u7l1"
}

Response samples

Content type
application/json
{
  • "error": "Error retrieving the resource.",
  • "details": "Specific details about the error, depending on the case."
}

Run an item's slash command

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 7l37isroz4e63giev62hs318bn

ID of the playbook run whose item will be executed.

checklist
required
integer
Example: 1

Zero-based index of the checklist whose item will be executed.

item
required
integer
Example: 2

Zero-based index of the item whose slash command will be executed.

Responses

Request samples

curl -X POST 'http://localhost:8065/plugins/playbooks/api/v0/runs/7l37isroz4e63giev62hs318bn/checklists/1/item/2/run' \
-H 'Authorization: Bearer 9g64ig7q9pds8yjz8rsgd6e36e'

Response samples

Content type
application/json
{
  • "trigger_id": "ceenjwsg6tgdzjpofxqemy1aio"
}

PlaybookAutofollows

Playbook Autofollows

Get the list of followers' user IDs of a playbook

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: iz0g457ikesz55dhxcfa0fk9yy

ID of the playbook to retrieve followers from.

Responses

Request samples

curl -X GET 'http://localhost:8065/plugins/playbooks/api/v0/playbooks/iz0g457ikesz55dhxcfa0fk9yy/autofollows' \
-H 'Authorization: Bearer 9g64ig7q9pds8yjz8rsgd6e36e'

Response samples

Content type
application/json
{
  • "total_count": 12,
  • "items": [
    ]
}

Timeline

Timeline

Remove a timeline event from the playbook run

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: zjy2q2iy2jafl0lo2oddos5xn7

ID of the playbook run whose timeline event will be modified.

event_id
required
string
Example: craxgf4r4trgzrtues3a1t74ac

ID of the timeline event to be deleted

Responses

Request samples

curl -X DELETE 'http://localhost:8065/plugins/playbooks/api/v0/runs/zjy2q2iy2jafl0lo2oddos5xn7/timeline/craxgf4r4trgzrtues3a1t74ac' \
-H 'Authorization: Bearer 9g64ig7q9pds8yjz8rsgd6e36e'

Response samples

Content type
application/json
{
  • "error": "Error retrieving the resource.",
  • "details": "Specific details about the error, depending on the case."
}

Internal

Internal endpoints

Create a new playbook run from dialog

This is an internal endpoint to create a playbook run from the submission of an interactive dialog, filled by a user in the webapp. See Interactive Dialogs for more information.

Authorizations:
BearerAuth
Request Body schema: application/json

Dialog submission payload.

type
string
url
string
callback_id
string

Callback ID provided by the integration.

state
string

Stringified JSON with the post_id and the client_id.

user_id
string

ID of the user who submitted the dialog.

channel_id
string

ID of the channel the user was in when submitting the dialog.

team_id
string

ID of the team the user was on when submitting the dialog.

object

Map of the dialog fields to their values

cancelled
boolean

If the dialog was cancelled.

Responses

Request samples

Content type
application/json
{
  • "type": "dialog_submission",
  • "url": "string",
  • "callback_id": "string",
  • "state": "string",
  • "user_id": "string",
  • "channel_id": "string",
  • "team_id": "string",
  • "submission": {
    },
  • "cancelled": true
}

Response samples

Content type
application/json
{
  • "id": "mx3xyzdojfgyfdx8sc8of1gdme",
  • "name": "Server down in EU cluster",
  • "description": "There is one server in the EU cluster that is not responding since April 12.",
  • "is_active": true,
  • "owner_user_id": "bqnbdf8uc0a8yz4i39qrpgkvtg",
  • "team_id": "61ji2mpflefup3cnuif80r5rde",
  • "channel_id": "hwrmiyzj3kadcilh3ukfcnsbt6",
  • "create_at": 1606807976289,
  • "end_at": 0,
  • "delete_at": 0,
  • "active_stage": 1,
  • "active_stage_title": "Triage issue",
  • "post_id": "b2ntfcrl4ujivl456ab4b3aago",
  • "playbook_id": "0y4a0ntte97cxvfont8y84wa7x",
  • "checklists": [
    ]
}

Get autocomplete data for /playbook check

This is an internal endpoint used by the autocomplete system to retrieve the data needed to show the list of items that the user can check.

Authorizations:
BearerAuth
query Parameters
channel_ID
required
string
Example: channel_ID=r3vk8jdys4rlya46xhdthatoyx

ID of the channel the user is in.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

End a playbook run from dialog

This is an internal endpoint to end a playbook run via a confirmation dialog, submitted by a user in the webapp.

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 1igmynxs77ywmcbwbsujzktter

ID of the playbook run to end.

Responses

Request samples

curl -X POST 'http://localhost:8065/plugins/playbooks/api/v0/runs/1igmynxs77ywmcbwbsujzktter/end' \
-H 'Authorization: Bearer 9g64ig7q9pds8yjz8rsgd6e36e'

Response samples

Content type
application/json
{
  • "error": "Error retrieving the resource.",
  • "details": "Specific details about the error, depending on the case."
}

Go to next stage from dialog

This is an internal endpoint to go to the next stage via a confirmation dialog, submitted by a user in the webapp.

Authorizations:
BearerAuth
path Parameters
id
required
string

The PlaybookRun ID

Request Body schema: application/json

Dialog submission payload.

state
string

String representation of the zero-based index of the stage to go to.

Responses

Request samples

Content type
application/json
{
  • "state": "3"
}

Response samples

Content type
application/json
{
  • "error": "Error retrieving the resource.",
  • "details": "Specific details about the error, depending on the case."
}