---
title: "Directory"
slug: "directory-1"
updated: 2026-09-03T14:50:33Z
published: 2026-09-03T14:50:33Z
canonical: "developer.rocket.chat/directory-1"
stale: true
---

> ## Documentation Index
> Fetch the complete documentation index at: https://developer.rocket.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# Directory

Get/api/v1/directory

Search workspace directory for users, channels and teams.

### Changelog

| Version | Description |
| --- | --- |
| 7.0.0 | Added `type`, `workspace` and `text` query parameters |
| 1.0.0 | Added workspace query param |
| 0.65.0 | Added Pagination fields: count, total, offset |
| 0.64.0 | Added |

Header parametersX-Auth-TokenstringRequired

The `authToken` of the authenticated user.

ExampleRScctEHSmLGZGywfIhWyRpyofhKOiMoUIpimhvheU3f
X-User-IdstringRequired

The `userId` of the authenticated user.

ExamplerbAXPnMktTFbNpwtJ

Query parameterstextstring

The search term to be filtered

Examplerocket
typestring

It can be `channels` or `users`. When `type` is users you can send an additional workspace field, that can be local (default) or all. Workspace=all will work only if [federation](https://docs.rocket.chat/use-rocket.chat/rocket.chat-federation) is enabled.

Exampleusers
workspacestring

It can be `local` or `all`( if federation is enabled). It is `local` by default.

Examplelocal
queryRequired

The query to search the workspace directory. When `type` is users you can send an additional workspace field, that can be local (default) or all. Workspace=all will work only if [federation](https://docs.rocket.chat/use-rocket.chat/rocket.chat-federation) is enabled.

Example{"text": "rocket", "type": "users", "workspace": "local"}
offsetinteger

Number of items to "skip" in the query, i.e. requests return count items, skipping the first offset items. Refer to the [official documentation](https://developer.rocket.chat/apidocs/query-parameters#pagination) to learn more.

Example50
countinteger

The number of items to return. Refer to the [official documentation](https://developer.rocket.chat/apidocs/query-parameters#pagination) to learn more.

Example50
sort

List of fields to order by, and in which direction. This is a JSON object, with properties listed in desired order, with values of 1 for ascending, or -1 for descending. For example, {"value": -1, "_id": 1}. Refer to the [official documentation](https://developer.rocket.chat/apidocs/query-parameters#pagination) to learn more.

fieldsstring

This parameter accepts a JSON object with properties that have a value of 1 or 0 to include or exclude them in the response. For example, to only retrieve the usernames of users: `fields={ "username": 1 }`. Refer to the [official documentation](https://developer.rocket.chat/apidocs/query-parameters#query-and-fields) to learn more.

Responses200

OK

<select class='api-response-data' aria-label='Media type'><option value='17d490b3-e8b6-401d-893f-19064fc42dac'>application/json</option>
</select><select class='select-example' aria-label='Media type'><option value='94cc3771-670e-46dc-b159-bc3310138a15'>Success</option>
</select>Success

```json
{
  "result": [
    {
      "_id": "jRca8kibJx8NkLJxt",
      "createdAt": "2018-04-13T12:46:26.517Z",
      "emails": [
        {
          "address": "user.test.1523623548558@rocket.chat",
          "verified": false
        }
      ],
      "name": "EditedRealNameuser.test.1523623548558",
      "username": "editedusernameuser.test.1523623548558",
      "avatarETag": "6YbLtc4v9b4conXon"
    }
  ],
  "count": 1,
  "offset": 0,
  "total": 1,
  "success": true
}
```

Expand Allobject  result Array of object   object  _idstring    
createdAtstring    
emails Array of object   object  addressstring    
verifiedboolean    

namestring    
usernamestring    
avatarETagstring    

countinteger    
offsetinteger    
totalinteger    
successboolean    

401

Unauthorized

<select class='api-response-data' aria-label='Media type'><option value='ca7cba5f-cc23-4b5e-85fb-fc90dbf7161b'>application/json</option>
</select><select class='select-example' aria-label='Media type'><option value='8ce2e0ed-2f3d-4b3c-b462-f19f1c8e1b62'>Authorization Error</option>
</select>Authorization Error

```json
{
  "status": "error",
  "message": "You must be logged in to do this."
}
```

object  statusstring    
messagestring