Create Folder

Create a folder in a repository, at the top level or inside another folder.

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

cURL

curl -X POST "https://api.wordsmith.ai/api/v1/repositories/b23066a1-44cb-4b31-8b44-c723dc507d9b/folders" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Retail units",
    "parent_id": "78efa174-bd3a-4d65-aea9-40f510e973fd"
  }'

Response

{
  "id": "d85cb28c-9081-4b90-90be-be843b16c493",
  "name": "Retail units",
  "parent_id": "78efa174-bd3a-4d65-aea9-40f510e973fd"
}

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

Creates a folder in a repository. Folders organise documents, and you can limit a search or a document list to one.

Pass the new folder’s id as folder_id to Add Documents to put documents in it. A folder synced from a connected source takes no new folders or documents.

Authentication

Requires an API key, or an OAuth token with repositories:write. The caller also needs edit access to the repository.

Path parameters

repository_id · string · required

The repository id.

Body parameters

name · string · required

The folder name, up to 200 characters.

parent_id · string

The folder to create this one inside. Leave it out to create a top-level folder.

Response

Returns 201 with the new folder: id, name and parent_id.

cURL

curl -X POST "https://api.wordsmith.ai/api/v1/repositories/b23066a1-44cb-4b31-8b44-c723dc507d9b/folders" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Retail units",
    "parent_id": "78efa174-bd3a-4d65-aea9-40f510e973fd"
  }'

Response

{
  "id": "d85cb28c-9081-4b90-90be-be843b16c493",
  "name": "Retail units",
  "parent_id": "78efa174-bd3a-4d65-aea9-40f510e973fd"
}

Errors

Status	error_code	When
400	invalid_request_body	name is missing, empty or longer than 200 characters, or the body has an unknown field.
400	bad_request	The name is not allowed as a folder name, or parent_id is a folder synced from a connected source.
401	unauthorized	The API key or token is missing or invalid.
403	mcp_not_enabled	Your organisation is not in the preview.
403	forbidden	The caller can read the repository but cannot edit it.
404	resource_not_found	No repository with this id, the caller cannot read it, or parent_id is not a folder in it.
409	resource_conflict	The parent folder changed at the same time. Retry.