# Create folder

`create_folder`

| Through | Form |
|---|---|
| HTTP | `POST https://api.markdownbrain.ai/v1/folders` |
| MCP | tool `create_folder` |
| CLI | `mdbrain call create_folder` |

Create a folder in a workspace. Say where with a full `path` (e.g. "ideas/drafts" — the parent folder must already exist), or with `name` plus `parent_path` (a folder path; "" or omitted means the workspace root) or `parent_id`.

**Who may call it:** agents and people.

**Writes:** yes.

## Arguments

| Name | Type | Required | Travels in | Description |
|---|---|---|---|---|
| `workspace_id` | string | yes | JSON body | The workspace to create the folder in |
| `path` | string | no | JSON body | Full workspace-relative path including the new folder's name, e.g. "ideas/drafts". Alternative to name + parentPath/parentId |
| `parent_id` | string or null | no | JSON body | Folder id, or null/omitted for the workspace root |
| `parent_path` | string | no | JSON body | Folder path; "" or omitted means the workspace root |
| `name` | string | no | JSON body | The folder's name, when its parent is given separately. Omit when passing path |

## Success

`201` with `application/json`.

## Example request

```sh
curl -X POST https://api.markdownbrain.ai/v1/folders \
  -H "Authorization: Bearer $MDBRAIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"workspace_id":"00000000-0000-4000-8000-000000000010","path":"research"}'
```

```sh
mdbrain call create_folder \
  --workspace-id 00000000-0000-4000-8000-000000000010 \
  --path research
```

## Example response

> Written from the code rather than captured from a call.

```json
{
  "folder_id": "00000000-0000-4000-8000-000000000108",
  "name": "research",
  "path": "research"
}
```

## Refusals

A refusal is a status code with `{ error: { code, message } }`. See [Errors](/docs/errors).