Create Folder

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

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

POST

api

repositories

{repository_id}

folders

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

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

string

required

The repository id.

Body parameters

string

required

The folder name, up to 200 characters.

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

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

Preview

Agents, playbooks and blueprints

Sessions

Playbook authoring

Drafts

Files

Document actions

Operations

Research

Reports

Reviews

Organisation

Sharing

Usage and value

Repositories and search

Authentication

Path parameters

Body parameters

Response

Errors

​Authentication

​Path parameters

​Body parameters

​Response

​Errors

Authentication

Path parameters

Body parameters

Response

Errors