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

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

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.

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

Refusals

A refusal is a status code with { error: { code, message } }. See Errors.