Rocket.Chat API

Welcome to the Rocket.Chat API documentation! This guide is designed to help you interact effectively with Rocket.Chat’s REST API endpoints, Realtime API methods, and Livechat Widget API.

Our APIs enable you to integrate, automate, and extend Rocket.Chat, allowing you to manage workspaces, users, rooms, and applications, and to build rich communication experiences.

You are in the API reference for REST endpoints, Realtime API methods, and the Livechat Widget API. For tutorials, development environment setup, and Apps-Engine guides, see the developer guides.

Base URL

All REST API endpoints are relative to your workspace URL:

https://<your-workspace-url>/api/v1/

For example, if your workspace runs at https://chat.example.com, the endpoint to list channels is https://chat.example.com/api/v1/channels.list.

Make your first API call

Follow these steps to authenticate and call your first endpoint:

curl -X POST https://<your-workspace-url>/api/v1/login \
     -H "Content-Type: application/json" \
     -d '{ "user": "your-username", "password": "your-password" }'

The response returns your credentials in data.userId and data.authToken.

Pass these values as headers in every authenticated request:

curl https://<your-workspace-url>/api/v1/channels.list \
     -H "X-Auth-Token: your-auth-token" \
     -H "X-User-Id: your-user-id"

For scripts and integrations, use a personal access token instead of a password login. See the Authentication endpoints for all available login methods.

Response format

All REST API responses return JSON. Successful calls return the requested data with a success flag:

{
  "channels": [ ... ],
  "success": true
}

Failed calls return "success": false with an error message and an HTTP status code such as 400, 401, or 403:

{
  "success": false,
  "error": "Body parameter \"name\" is required.",
  "errorType": "error-invalid-params"
}

Pagination and queries

Endpoints that return lists accept these query parameters:

count: The number of items to return.
offset: The number of items to skip.
sort: A JSON object with the fields to sort by, using 1 for ascending and -1 for descending.

For example: /api/v1/channels.list?count=50&offset=100&sort={"name":1}

See Query parameters for the full list of supported parameters.

Available APIs

Rocket.Chat provides the following APIs:

Rocket.Chat’s REST API

Follows REST (Representational State Transfer) principles and supports standard HTTP methods, GET, POST, PUT, and DELETE, for performing operations on various resources.

Livechat Widget API

Enables developers to integrate Omnichannel Livechat functionalities directly into their applications.

Realtime API

This allows developers to integrate Rocket.Chat’s real-time messaging and collaboration features in their applications through websockets.

Additional information

Schema definition provides an overview of the structure and fields used in Rocket.Chat schema. Deprecated endpoints and parameters provide details on deprecated and removed endpoints and parameters.

Download the OpenAPI specification to generate API clients or power your own tooling.

Rocket.Chat REST API

Security considerations for production environments

Securing your production environment is essential when using the Rocket.Chat REST API. Follow these guidelines to help ensure data confidentiality and prevent unauthorized access:

Always use the Login API exclusively over HTTPS during authentication to protect user credentials.
Enforce a strict token management policy that includes regular token expiration and renewal to minimize the risk of unauthorized access.
Carefully configure user permissions. Assigning precise access rights to endpoints is critical to prevent unauthorized actions and potential data breaches.

Rate Limiting

Rate limiting is an essential mechanism in Rocket.Chat that controls the frequency of API requests. It helps maintain server stability, prevent misuse, and ensure fair resource usage across all users. By default, rate limiting is enabled for all endpoints.

Enabling and configuring the rate limiter

To enable or modify rate limiting in your workspace:

Go to Manage → Workspace → Settings → Rate Limiter → API Rate Limiter.
Adjust the following settings as needed:
- Enable Rate Limiter: Activates rate limiting for REST API endpoints.
- Enable Rate Limiter in Development: Applies rate limiting in the development environment.
- Default number of calls to the rate limiter: Defines the number of API calls allowed per endpoint within the configured time window.
- Default time limit for the rate limiter (in ms): Specifies the time window (in milliseconds) used for counting requests.
Click Save Changes

To disable the rate limiter, assign the api-bypass-rate-limit permission to the appropriate user role.

Additional rate limiting options

DDP Rate Limit: Controls the rate of requests sent or received through the DDP protocol to prevent excessive message traffic.
Feature Limiting: Allows you to restrict access or limit usage of specific Rocket.Chat features, providing another layer of protection against overuse.

Customizing rate limits in code

To modify or disable rate limiting for a specific API endpoint programmatically, use the .addRoute function and configure the rateLimiterOptions property within the route definition.

Set rateLimiterOptions: false to disable rate limiting for that endpoint.
Alternatively, define a custom configuration object, e.g.:
```
{ numRequestsAllowed: 10, intervalTimeInMS: 60000 }
```
to control the number of allowed requests and the reset interval.

Response headers

When rate limiting is enabled, API responses include the following headers:

x-ratelimit-limit: Maximum number of calls allowed in the current window.
x-ratelimit-remaining: Number of remaining calls available before the limit resets.
x-ratelimit-reset: Time (in UTC epoch milliseconds) when the rate limit will reset.

These headers help you monitor and manage your application’s request usage in real time.

Some endpoints, such as /api/v1/users.updateOwnBasicInfo, always trigger rate limiting and cannot be customized or disabled through the administration panel.

Language-specific wrappers

Rocket.Chat does not maintain these wrappers. They are developed and supported by community contributors.

You can use the following community-maintained libraries to interact with Rocket.Chat APIs in different programming languages:

Language	Wrapper
Java	rocket-chat-rest-client
PHP	rocketchat-php
Python	rocketchat_API rocket-python
Ruby	rocketchat-ruby
Clojure	rocketchat-clojure
Golang	rocketchat-golang

If your preferred language isn’t listed, you can submit a feature request to suggest adding new API wrappers to Rocket.Chat.

Documentation Index