List Documents

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

GET /api/v1/repositories/{repository_id}/documents

cURL

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"

Response

{
  "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
}

Preview. This endpoint is available to organisations in the Wordsmith MCP pilot. Other organisations receive 403 mcp_not_enabled. See the preview overview.

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. 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[]

Show 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

cURL

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"

Response

{
  "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.