List Folders

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

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

cURL

curl "https://api.wordsmith.ai/api/v1/repositories/b23066a1-44cb-4b31-8b44-c723dc507d9b/folders" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here"

Response

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

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

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, List Documents or 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.

cURL

curl "https://api.wordsmith.ai/api/v1/repositories/b23066a1-44cb-4b31-8b44-c723dc507d9b/folders" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here"

Response

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