README.md

Rocket.Chat 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.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

• rocket-chat-rest-client

PHP

• rocket-chat-rest-client

Python

• rocketchat_API

Ruby

• rocketchat-ruby

Clojure

• rocketchat-clojure