REST API

The REST API allows you to control and extend Rocket.Chat with ease.

This API is a work in progress, so feel free to test, ask us questions, and submit Pull Requests!

If you are an end-user and not a dev or a tester, create a New Feature Request to request new APIs -- and consider making a donation to the project.

All API calls in the documentation are made using curl. However, you are free to use Java / Python / PHP / Golang / Ruby / Swift / Objective-C / Rust / Scala / C# or any other programming languages.

Production Security Concerns

When calling a production Rocket.Chat server, ensure it is running via HTTPS and has a valid SSL Certificate. The login method requires you to post your username and password in plaintext, which is why we highly suggest only calling the REST login API over HTTPS. Also, few things to note:

  • Only call via HTTPS

  • Implement a timed authorization token expiration strategy

  • Ensure the calling user only has permissions for what they are calling and no more

Miscellaneous Information

Url

Short Description

Details Page

/api/info

Information about the Rocket.Chat server.

Link

/api/v1/directory

Search by all users and channels available on server.

Link

/api/v1/shield.svg

Gets the shield svg(badge) to add in your website.

Link

/api/v1/spotlight

Searches for users or rooms that are visible to the user.

Link

/api/v1/statistics

Statistics about the Rocket.Chat server.

Link

/api/v1/statistics.list

Selectable statistics about the Rocket.Chat server.

Link

Assets

Url

Short Description

Details Page

/api/v1/assets.setAsset

Set an asset image by name.

Link

/api/v1/assets.unsetAsset

Unset an asset by name

Link

AutoTranslate

Url

Short Description

Details Page

/api/v1/autotranslate.getSupportedLanguages

Get the supported languages by the autotranslate.

Link

/api/v1/autotranslate.saveSetttings

Save some settings about autotranslate.

Link

/api/v1/autotranslate.translateMessage

Translate the message.

Link

Authentication

Url

Short Description

Details Page

/api/v1/login

Authenticate with the REST API.

Link

/api/v1/login

Authenticate with google.

Link

/api/v1/login

Authenticate with facebook.

Link

/api/v1/login

Authenticate with twitter.

Link

/api/v1/logout

Invalidate your REST API authentication token.

Link

/api/v1/me

Displays information about the authenticated user.

Link

Users

Url

Short Description

Details Page

/api/v1/users.presence

Gets all connected users presence.

Link

/api/v1/users.create

Create a new user.

Link

/api/v1/users.createToken

Create a user authentication token.

Link

/api/v1/users.deactivateIdle

Deactivate idle users.

Link

/api/v1/users.delete

Deletes an existing user.

Link

/api/v1/users.deleteOwnAccount

Deletes your own user.

Link

/api/v1/users.forgotPassword

Send email to reset your password.

Link

/api/v1/users.generatePersonalAccessToken

Generate Personal Access Token.

Link

/api/v1/users.getAvatar

Gets the URL for a user's avatar.

Link

/api/v1/users.getPersonalAccessTokens

Gets the user's personal access tokens.

Link

/api/v1/users.getPreferences

Gets all preferences of user.

Link

/api/v1/users.getPresence

Gets the online presence of a user.

Link

/api/v1/users.getStatus

Gets the user's status.

Link

/api/v1/users.getUsernameSuggestion

Gets a suggestion a new username to user.

Link

/api/v1/users.info

Gets a user's information, limited to the caller's permissions.

Link

/api/v1/users.list

All of the users and their information, limited to permissions.

Link

/api/v1/users.regeneratePersonalAccessToken

Regenerate a user personal access token.

Link

/api/v1/users.register

Register a new user.

Link

/api/v1/users.removeOtherTokens

Remove all other user tokens

Link

/api/v1/users.removePersonalAccessToken

Remove a personal access token.

Link

/api/v1/users.requestDataDownload

Request users download data.

Link

/api/v1/users.resetAvatar

Reset a user's avatar

Link

/api/v1/users.setAvatar

Set a user's avatar

Link

/api/v1/users.setPreferences

Set user's preferences

Link

/api/v1/users.setStatus

Set the user's status

Link

/api/v1/users.setActiveStatus

Set a user's active status.

Link

/api/v1/users.update

Update an existing user.

Link

/api/v1/users.updateOwnBasicInfo

Update basic information of own user.

Link

Channels

Url

Short Description

Details Page

/api/v1/channels.addAll

Adds all of the users on the server to a channel.

Link

/api/v1/channels.addLeader

Gives the role of Leader for a user in the current channel.

Link

/api/v1/channels.addOwner

Gives the role of owner for a user in the current channel.

Link

/api/v1/channels.anonymousread

Gets the messages in public channels to an anonymous user

Link

/api/v1/channels.archive

Archives a channel.

Link

/api/v1/channels.cleanHistory

Cleans up a channel's history, requires special permission.

Link

/api/v1/channels.close

Removes a channel from a user's list of channels.

Link

/api/v1/channels.counters

Gets channel counters.

Link

/api/v1/channels.create

Creates a new channel.

Link

/api/v1/channels.delete

Removes a channel.

Link

/api/v1/channels.files

Gets a list of files from a channel.

Link

/api/v1/channels.getAllUserMentionsByChannel

Gets all the mentions of a channel.

Link

/api/v1/channels.getIntegrations

Gets the channel's integration.

Link

/api/v1/channels.history

Retrieves the messages from a channel.

Link

/api/v1/channels.info

Gets a channel's information.

Link

/api/v1/channels.invite

Adds a user to a channel.

Link

/api/v1/channels.join

Joins yourself to a channel.

Link

/api/v1/channels.kick

Removes a user from a channel.

Link

/api/v1/channels.leave

Removes the calling user from a channel.

Link

/api/v1/channels.list

Retrieves all of the channels from the server.

Link

/api/v1/channels.list.joined

Gets only the channels the calling user has joined.

Link

/api/v1/channels.members

Retrieves all channel users.

Link

/api/v1/channels.messages

Retrieves all channel messages.

Link

/api/v1/channels.moderators

List all moderators of a channel.

Link

/api/v1/channels.online

List all online users of a channel.

Link

/api/v1/channels.open

Adds the channel back to the user's list of channels.

Link

/api/v1/channels.removeleader

Removes the role of Leader for a user in the current channel.

Link

/api/v1/channels.rename

Changes a channel's name.

Link

/api/v1/channels.roles

Gets the user's roles in the channel.

Link

/api/v1/channels.setCustomFields

Sets a channel's custom fields.

Link

/api/v1/channels.setAnnouncement

Sets a channel's announcement.

Link

/api/v1/channels.setDefault

Sets whether a channel is a default channel or not.

Link

/api/v1/channels.setDescription

Sets a channel's description.

Link

/api/v1/channels.setJoinCode

Sets the channel's code required to join it.

Link

/api/v1/channels.setPurpose

Sets a channel's description.

Link

/api/v1/channels.setReadOnly

Sets whether a channel is read only or not.

Link

/api/v1/channels.setTopic

Sets a channel's topic.

Link

/api/v1/channels.setType

Sets the type of room the channel should be.

Link

/api/v1/channels.unarchive

Unarchives a channel.

Link

/api/v1/channels.addOwner

Gives the role of owner for a user in the current channel.

Link

/api/v1/channels.removeOwner

Removes the role of owner from a user in the current channel.

Link

Groups

Url

Short Description

Details Page

/api/v1/groups.archive

Archives a private group.

Link

/api/v1/groups.addLeader

Gives the role of Leader for a user in the current group.

Link

/api/v1/groups.close

Removes a private group from the list of groups.

Link

/api/v1/groups.counters

Gets group counters.

Link

/api/v1/groups.create

Creates a new private group.

Link

/api/v1/groups.delete

Removes a private group.

Link

/api/v1/groups.files

Gets a list of files from a private group.

Link

/api/v1/groups.history

Retrieves the messages from a private group.

Link

/api/v1/groups.info

Gets the information about a private group.

Link

/api/v1/groups.invite

Adds a user to the private group.

Link

/api/v1/groups.kick

Removes a user from a private group.

Link

/api/v1/groups.leave

Removes the calling user from the private group.

Link

/api/v1/groups.list

List the private groups the caller is part of.

Link

/api/v1/groups.listAll

List all the private groups.

Link

/api/v1/groups.members

Gets the users of participants of a private group.

Link

/api/v1/groups.messages

Retrieves all group messages.

Link

/api/v1/groups.moderators

List all moderators of a group.

Link

/api/v1/groups.online

List all online users of a group.

Link

/api/v1/groups.open

Adds the private group back to the list of groups.

Link

/api/v1/groups.removeLeader

Removes the role of Leader for a user in the current group.

Link

/api/v1/groups.rename

Changes the name of the private group.

Link

/api/v1/groups.roles

Gets the user's roles in the private group.

Link

/api/v1/groups.setAnnouncement

Sets a group's announcement.

Link

/api/v1/groups.setCustomFields

Sets private group's custom fields.

Link

/api/v1/groups.setDescription

Sets a private group's description.

Link

/api/v1/groups.setPurpose

Sets a private group's description.

Link

/api/v1/groups.setReadOnly

Sets whether the room is read only or not.

Link

/api/v1/groups.setTopic

Sets a private group's topic.

Link

/api/v1/groups.setType

Sets the type of room this group will be.

Link

/api/v1/groups.unarchive

Unarchives a private group.

Link

/api/v1/groups.addOwner

Gives the role of owner for a user in the current group.

Link

/api/v1/groups.removeOwner

Removes the role of owner from a user in the current Group.

Link

Chat

Url

Short Description

Details Page

/api/v1/chat.delete

Deletes an existing chat message.

Link

/api/v1/chat.followMessage

Follows an existing chat message.

Link

/api/v1/chat.getDeletedMessages

Retrieves the deleted messages since specific date.

Link

/api/v1/chat.getDiscussions

Retrieves the discussions messages of a room.

Link

/api/v1/chat.getMentionedMessages

Retrieves mentioned messages.

Link

/api/v1/chat.getMessage

Retrieves a single chat message.

Link

/api/v1/chat.getMessageReadReceipts

Retrieves message read receipts.

Link

/api/v1/chat.getPinnedMessages

Retrieve pinned messages from a room.

Link

/api/v1/chat.getSnippetedMessages

Retrieves snippeted messages.

Link

/api/v1/chat.getSnippetedMessageById

Retrieves snippeted message by id.

Link

/api/v1/chat.getStarredMessages

Retrieves starred messages.

Link

/api/v1/chat.getThreadMessages

Retrieves thread's messages.

Link

/api/v1/chat.getThreadsList

Retrieves channel's threads.

Link

/api/v1/chat.ignoreUser

Ignores an user from a chat.

Link

/api/v1/chat.pinMessage

Pins a chat message to the message's channel.

Link

/api/v1/chat.postMessage

Posts a new chat message.

Link

/api/v1/chat.react

Sets/unsets the user's reaction to an existing chat message.

Link

/api/v1/chat.reportMessage

Reports a message.

Link

/api/v1/chat.search

Search for messages in a channel.

Link

/api/v1/chat.starMessage

Stars a chat message for the authenticated user.

Link

/api/v1/chat.sendMessage

Send new chat message.

Link

/api/v1/chat.syncThreadMessages

Retrieves synced thread's messages.

Link

/api/v1/chat.syncThreadsList

Retrieves thread's synced channel threads.

Link

/api/v1/chat.unfollowMessage

Unfollows an existing chat message.

Link

/api/v1/chat.unPinMessage

Removes the pinned status of the provided chat message.

Link

/api/v1/chat.unStarMessage

Removes the star on the chat message for the authenticated user.

Link

/api/v1/chat.update

Updates the text of the chat message.

Link

Custom Sounds

Url

Short Description

Details Page

/api/v1/custom-sounds.list

Retrieves a list of custom sounds.

Link

IM

Url

Short Description

Details Page

/api/v1/im.close

Removes a direct message from the list of direct messages.

Link

/api/v1/im.counters

Gets counters of direct messages.

Link

/api/v1/im.create

Create a direct message session with another user.

Link

/api/v1/im.history

Retrieves the messages from a direct message.

Link

/api/v1/im.files

Retrieves a list of files from a direct message.

Link

/api/v1/im.members

Retrieves the users of participants of a direct message.

Link

/api/v1/im.messages

Retrieves the messages from specific direct message.

Link

/api/v1/im.messages.others

Retrieves the messages from any direct message in the server.

Link

/api/v1/im.list

List the direct messages the caller is part of.

Link

/api/v1/im.list.everyone

List all direct message the caller in the server.

Link

/api/v1/im.open

Adds the direct message back to the list of direct messages.

Link

/api/v1/im.setTopic

Sets a direct message topic.

Link

Integrations

Url

Short Description

Details Page

/api/v1/integrations.create

Creates an integration.

Link

/api/v1/integrations.get

Gets an integration.

Link

/api/v1/integrations.history

Lists all history of the specified integration.

Link

/api/v1/integrations.list

Lists all of the integrations.

Link

/api/v1/integrations.remove

Removes an integration.

Link

Invites

Url

Short Description

Details Page

/api/v1/findOrCreateInvite

Created a new Invite or returns an existing one with the same parameters.

Link

/api/v1/listInvites

Lists all of the invite tokens.

Link

/api/v1/removeInvite

Removes an invite.

Link

/api/v1/useInviteToken

Report to the server that an invite token was used.

Link

/api/v1/validateInviteToken

Checks if an invite token is valid.

Link

Livechat

Url

Short Description

Details Page

/api/v1/livechat/inquiries.list

Retrieves a list of open inquiries.

Link

/api/v1/livechat/inquiries.take

Take an open inquiry.

Link

/api/v1/livechat/rooms

Retrieves a list of livechat rooms.

Link

OAuthApps

Url

Short Description

Details Page

/api/v1/oauth-apps.get

Retrieves an OAuth App by id or client id.

Link

/api/v1/oauth-apps.list

Retrieves a list of OAuth Apps.

Link

Permissions

Url

Short Description

Details Page

/api/v1/permissions.listAll

Lists permissions on the server.

Link

/api/v1/permissions.update

Edits permissions on the server.

Link

Roles

Url

Short Description

Details Page

/api/v1/roles.create

Create a new role in the system.

Link

/api/v1/roles.list

Gets all the roles in the system.

Link

/api/v1/roles.sync

Gets all the roles in the system which are updated after a given date.

Link

/api/v1/roles.addUserToRole

Assign a role to an user.

Link

/api/v1/roles.getUsersInRole

Gets the users that belongs to a role.

Link

Push Token

Url

Method

Short Description

Details Page

/api/v1/push.token

POST

Saves push token.

Link

/api/v1/push.token

DELETE

Removes push token.

Link

Rooms

Url

Short Description

Details Page

/api/v1/rooms.adminRooms

Retrieve all rooms (requires special permission).

Link

/api/v1/rooms.cleanHistory

Cleans up a room's history, requires special permission.

Link

/api/v1/rooms.createDiscussion

Creates a new discussion.

Link

/api/v1/rooms.favorite

Favorite/Unfavorite room.

Link

/api/v1/rooms.get

Gets rooms.

Link

/api/v1/rooms.getDiscussions

Gets room's discussions.

Link

/api/v1/rooms.info

Gets info from a room.

Link

/api/v1/rooms.leave

Leaves a room.

Link

/api/v1/rooms.saveNotification

Sets the notifications settings of specific channel.

Link

/api/v1/rooms.upload/:rid

Upload a message with attached file.

Link

Command Methods

Url

Short Description

Details Page

/api/v1/commands.get

Get specification of the slash command.

Link

/api/v1/commands.list

Lists all available slash commands.

Link

/api/v1/commands.run

Execute a slash command in the specified room.

Link

Custom User Status

Url

Short Description

Details Page

/api/v1/custom-user-status.list

Lists all available custom user's status.

Link

Emoji Custom

Url

Short Description

Details Page

/api/v1/emoji-custom.list

List the custom emojis available.

Link

/api/v1/emoji-custom.create

Create new custom emoji.

Link

/api/v1/emoji-custom.delete

Delete an existent custom emoji.

Link

/api/v1/emoji-custom.update

Update an existent custom emoji.

Link

Settings

Url

Method

Short Description

Details Page

/api/v1/settings

GET

Lists all private settings.

Link

/api/v1/settings.public

GET

Lists all public settings.

Link

/api/v1/settings.oauth

GET

Return list of all available oauth services.

Link

/api/v1/service.configurations

GET

Lists all service configurations.

Link

/api/v1/settings/:_id

GET

Gets a setting.

Link

/api/v1/settings/:_id

POST

Updates a setting.

Link

Subscriptions

Url

Method

Short Description

Details Page

/api/v1/subscriptions.get

GET

Get all subscriptions.

Link

/api/v1/subscriptions.getOne

GET

Get the subscription by room Id.

Link

/api/v1/subscriptions.read

POST

Mark a room as read.

Link

/api/v1/subscriptions.unread

POST

Mark messages as unread.

Link

Video Conference

Url

Short Description

Details Page

/api/v1/video-conference/jitsi.update-timeout

Updates the timeout of Jitsi video conference in a channel.

Link

Webdav

Url

Short Description

Details Page

/api/v1/webdav.getMyAccounts

Retrieves the user's webdav accounts.

Link

Language specific wrappers

Java

PHP

Python

Ruby

Clojure