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

# Folders

> Find and open the folders you can reach: top-level folders, a name search across the tree, and one folder's path, subfolders, sessions and document count.

Find a folder by name, open it, and walk its subfolders. The documents filed
in a folder are listed with [`list_documents`](/reference/documents#list_documents)
`folder_id`; read, comment on and export them by `document_id` as usual.

| Tool | Scope | Kind |
| - | - | - |
| [`list_folders`](#list-folders) | `documents:read` | read-only |

## list\_folders

**Scope:** `documents:read` (step-up) · **Kind:** read-only · **Annotations:** `readOnlyHint: true`, `destructiveHint: false`, `openWorldHint: false`

> The folders you can open, as the sidebar shows them. With no arguments:
> your top-level folders by name. `query` finds folders by name anywhere in
> the tree, each with its `path`. `folder_id` opens one folder: its path,
> subfolders, sessions (newest activity first; `sessions_cursor` → call again
> with it as `cursor` for more) and how many documents are filed in it. List
> those documents with list\_documents `folder_id`, then read, comment on or
> export them by `document_id`. Subfolders are not expanded: open each with
> its own `folder_id`. `role` is your access (owner | participant | viewer);
> a viewer can read but not file documents into the folder.

### Parameters

Pass **at most one** of `folder_id` and `query`.

<ParamField body="folder_id" type="string">
  Open this folder.
</ParamField>

<ParamField body="query" type="string">
  Words from the folder name. Matches folders at any depth, only the ones you
  can open.
</ParamField>

<ParamField body="cursor" type="string">
  With `folder_id`: the `sessions_cursor` from the previous call, for the next
  page of the folder's sessions.
</ParamField>

<ParamField body="limit" type="number" default="50">
  Folders to return when listing or searching, 1 to 50. Clamped.
</ParamField>

### Returns

Without `folder_id`:

<ResponseField name="folders" type="object[]">
  Each `{folder_id, name, role, path, can_nest}`. `path` is the folder's
  ancestors from the top, each `{folder_id, name}` (empty at the top level).
  `can_nest` says whether it can hold subfolders.
</ResponseField>

<ResponseField name="truncated" type="boolean">
  More folders matched than were returned: narrow the `query`.
</ResponseField>

With `folder_id`:

<ResponseField name="folder" type="object">
  `{folder_id, name, description?, role, path, can_nest}`.
</ResponseField>

<ResponseField name="subfolders" type="object[]">
  Its direct subfolders you can open, same shape as `folders`.
  `subfolders_truncated` is true past 200.
</ResponseField>

<ResponseField name="sessions" type="object[]">
  Up to 50 sessions filed in the folder, newest activity first, each
  `{session_id, title, last_activity_at}`. `sessions_cursor` is a string when
  more exist.
</ResponseField>

<ResponseField name="artifact_count" type="number">
  Documents and pages filed directly in the folder, counted up to 50;
  `artifact_count_capped: true` means there are more (the text says `50+`).
</ResponseField>

### Permissions and side effects

You see a folder when you could open it in the app: you were added to it or
to a folder above it. Reading changes nothing.

### Errors

| Message | Cause |
| - | - |
| `Folder not found` | No such folder, or you can't open it — the same answer either way. |
| `Pass either folder_id or query, not both` | Both were sent. |
| `cursor pages a folder's sessions: pass it with folder_id` | `cursor` without `folder_id`. |

### Example

Review a folder end to end, without a browser:

```json theme={null}
{ "name": "list_folders", "arguments": { "query": "Customer research" } }
{ "name": "list_folders", "arguments": { "folder_id": "<folder_id>" } }
{ "name": "list_documents", "arguments": { "folder_id": "<folder_id>" } }
{ "name": "read_document", "arguments": { "document_id": "<document_id>" } }
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.