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

# Create Folder

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

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

Creates a folder in a repository. Folders organise documents, and you can limit a [search](/api-reference/repositories/search-repository) or a [document list](/api-reference/repositories/list-documents) to one.

Pass the new folder's `id` as `folder_id` to [Add Documents](/api-reference/repositories/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`.

```bash cURL theme={null}
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"
  }'
```

```json Response theme={null}
{
  "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. |


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