> ## 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 Documents

> List the documents in a repository, or in one folder of it.

> [!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).

Returns a page of the documents in a repository, sorted by name. Each document wraps one file and carries its indexing status. Documents synced from a connected source, such as a SharePoint folder, are listed too.

Pass `folder_id` to list only the documents directly in one folder. Find folder ids with [List Folders](/api-reference/repositories/list-folders). A page of a folder can hold fewer than `limit` documents, even none, while `cursor` is not `null`: its subfolders take up room in the page. Keep going until `cursor` is `null`.

To find documents that failed to index, walk the pages and check `indexing_status`.

## Authentication

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

## Path parameters

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

The repository id.

## Query parameters

**folder\_id** `string`

Only documents directly in this folder. Documents in its subfolders are not included.

**cursor** `string`

The `cursor` from the previous page. Leave it out for the first page.

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

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

## Response

Returns `200` with a page of documents. `cursor` is `null` on the last page.

**items** `object[]`

**properties**

**id** `string`

The document id. Not the `file_id`.

**file\_id** `string | null`

The uploaded file behind the document. `null` for a document synced from a connected source, such as SharePoint.

**file\_name** `string`

**folder\_id** `string | null`

The folder the document is in. `null` at the top level.

**indexing\_status** `string`

`pending` until it is indexed, then `indexed`. `failed` when indexing failed, or it has not finished two days after the document was added.

**created\_at** `string | null`

**cursor** `string | null`

```bash cURL theme={null}
curl "https://api.wordsmith.ai/api/v1/repositories/b23066a1-44cb-4b31-8b44-c723dc507d9b/documents?folder_id=d85cb28c-9081-4b90-90be-be843b16c493" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here"
```

```json Response theme={null}
{
  "items": [
    {
      "id": "612bf514-5c3e-468b-9782-d5d5a635b72d",
      "file_id": "5fd5db90-5cd3-46b6-87d9-c828732551ef",
      "file_name": "Lease - Unit 4 Riverside Park.pdf",
      "folder_id": "d85cb28c-9081-4b90-90be-be843b16c493",
      "indexing_status": "indexed",
      "created_at": "2026-10-13T09:14:22Z"
    },
    {
      "id": "ddb212bb-881b-4651-907b-70aa1350a68e",
      "file_id": "ee4c67ec-2355-4096-b147-f89ddef2029d",
      "file_name": "Lease - 18 Market Street (scan).pdf",
      "folder_id": "d85cb28c-9081-4b90-90be-be843b16c493",
      "indexing_status": "failed",
      "created_at": "2026-10-13T09:14:22Z"
    }
  ],
  "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 for the same `folder_id`. |
| 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 `folder_id` is not a folder in it. |


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