Query Parameters

Starting from version 0.49, specific endpoints in the Rocket.Chat API support the following query parameters:

  • Pagination

  • Query and fields

Pagination

The pagination query parameters are as follows:

Parameter

Example

Description

Format

offset

50

The number of items to "skip" in the query, i.e. requests return count items, skipping the first offset items.

Positive integer

count

50

The number of items to return.

Integer

sort

{"value": -1, "_id": 1}

List of fields to order by, and in which direction.

JSON object, with properties listed in the desired order, with values of 1 for ascending or -1 for descending.

Pagination parameter settings

To modify the offset and count behavior, you can access the REST API settings in Administration > Workspace > Settings > General > REST API.

  • Default Count: The default count for REST API results if the count parameter is not provided.

  • Max Record Amount: The maximum limit for the count parameter. If a higher count is specified, this limit will be applied.

  • Allow Getting Everything: This setting determines whether passing 0 as the count parameter is allowed to retrieve all records.

This feature provides flexibility in controlling the number of results, pagination, and sorting in the Rocket.Chat API.

Example call

  • To retrieve a specific page of results with five items per page, use the count=5 and offset=10 parameters in the API request:

http://localhost:3000/api/v1/channels.list?count=5&offset=10

  • To sort the results by name in descending order and status in ascending order, use the sort parameter with the appropriate JSON syntax:

 http://localhost:3000/api/v1/users.list?sort={"name":-1,"status":1}

Query and fields

The query and fields parameters have been deprecated since version 5.0.0 across all supported endpoints to prevent malicious queries. They are disabled by default from version 7.0.0 and can only be enabled by setting the ALLOW_UNSAFE_QUERY_AND_FIELDS_API_PARAMS: true environment variable in your deployment configuration.

Enabling these parameters may expose your workspace to security risks, and Rocket.Chat is not responsible for any resulting vulnerabilities. Proceed with caution and ensure proper security measures are in place.

When enabled, a deprecation message is included in the response header as X-Deprecation-Message. These parameters are scheduled for removal in version 8.0.0, after which enabling them will no longer be an option.

The query and fields parameters accept JSON objects, but the request will fail if an invalid JSON object is provided.

Parameter

Example

Description

query

To query users with a name that contains the letter "g":

https://localhost:3000/api/v1/users.list?query={ "name": { "$regex": "g" } }

This parameter allows you to use MongoDB query operators to search for specific data.

fields

To only retrieve the usernames of users:

http://localhost:3000/api/v1/users.list?fields={ "username": 1 }

This parameter accepts a JSON object with properties that have a value of 1 or 0 to include or exclude them in the response.

Note that the query parameter follows the EJSON structure, similar to JSON, but with some differences in handling date and binary fields. For queries involving date fields, you can use the following examples:

query={"_updatedAt": {"$gt": { "$date": 1542814057 } }}
 query={"_updatedAt":{"$gt":{"$date":"2018-11-21T15:27:28.202Z"}}}

If you provide a field value of {"_id": false, "value": false}, you can retrieve all other fields except for _id and value.

These query and field parameters enhance the flexibility and precision of data retrieval in the Rocket.Chat API.