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

# List Folders

> List the folders in a repository, so you can find a folder_id to file or search documents by.

> [!NOTE]
>
> **Preview.** This endpoint is available to organisations in the Wordsmith MCP pilot. Other organisations receive `403 mcp_not_enabled`. See the [preview overview](/preview).

Lists the folders in a repository, at every level, sorted by name. Build the tree from each folder's `parent_id`: top-level folders have `parent_id: null`. Folders synced from a connected source are listed too.

Use a folder's `id` as `folder_id` in [Add Documents](/api-reference/repositories/add-documents), [List Documents](/api-reference/repositories/list-documents) or [Search Repository](/api-reference/repositories/search-repository).

## Authentication

Requires an API key, or an OAuth token with `repositories:read`.

## Path parameters

**repository\_id** `string` *required*

The repository id.

## Query parameters

**parent\_id** `string`

Only the folders directly inside this folder. Leave it out to list every folder.

**cursor** `string`

The `cursor` from the previous page.

**limit** `integer` (default: 50)

Folders per page, from `1` to `100`.

## Response

Returns `200` with a page of folders: `id`, `name` and `parent_id`. `cursor` is `null` on the last page.

```bash cURL theme={null}
curl "https://api.wordsmith.ai/api/v1/repositories/b23066a1-44cb-4b31-8b44-c723dc507d9b/folders" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here"
```

```json Response theme={null}
{
  "items": [
    { "id": "78efa174-bd3a-4d65-aea9-40f510e973fd", "name": "Leases", "parent_id": null },
    { "id": "d85cb28c-9081-4b90-90be-be843b16c493", "name": "Retail units", "parent_id": "78efa174-bd3a-4d65-aea9-40f510e973fd" }
  ],
  "cursor": null
}
```

## Errors

| Status | `error_code` | When |
| - | - | - |
| 400 | `invalid_request_body` | `limit` is not a whole number from `1` to `100`. |
| 400 | `bad_request` | `cursor` is not one this endpoint returned. |
| 400 | `repository_folder_tree_too_large` | The repository has more than 5,000 folders. |
| 401 | `unauthorized` | The API key or token is missing or invalid. |
| 403 | `mcp_not_enabled` | Your organisation is not in the preview. |
| 404 | `resource_not_found` | No repository with this id, the caller cannot read it, or `parent_id` is not a folder in it. |


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