---
title: "Create a folder"
method: POST
path: "/v1/vault/folders"
tags: ["Vault"]
---

# Create a folder

`POST /v1/vault/folders`

## Request

- Base URL: `http://localhost:9998`
- URL: `http://localhost:9998/v1/vault/folders`
- Auth: HTTP bearer

Creates a folder marker blob under `parentPath`. Empty folders are
first-class — the marker is what lets one survive an index rebuild.
Returns the new folder as a bare tree node.

## Request body

- object
  - `parentPath` string, required: Parent folder's vault-relative path ('' for the vault root).
  - `name` string, required: Leaf name for the new folder.

## Response `200`

The created folder as a bare tree node

- WireVaultTreeNode: A node in the DECRYPTED vault tree. Recursive: a folder carries its children in tree responses. Mutation responses (note move, folder create/rename/move) return the bare relocated node with `children` omitted regardless of kind.
  - `id` string, required: Stable random UUID; unchanged by move/rename.
  - `kind` 'folder' | 'note', required: Whether a vault tree node is a folder or a note.
  - `name` string, required: Leaf display name, no path.
  - `path` string, required: Vault-relative, '/'-separated path, e.g. "ideas/2026/pitch".
  - `children` WireVaultTreeNode[]: Present on a folder in tree responses; omitted on a note and in mutation responses.

## Other responses

- `400`: Invalid request
- `404`: Parent folder not found
- `409`: The target path is already taken
- `423`: The vault is locked (no VMK loaded). Unlock natively in ToolPiper — there is no unlock route. The body is the standard nested error envelope with type `vault_locked`.
- `503`: Vault service unavailable

---

[API](https://skmtc.dev/modelpiper/apis/toolpiper-api.md) · [All operations](https://skmtc.dev/modelpiper/apis/toolpiper-api/llms.txt) · [OpenAPI document](https://skmtc.dev/modelpiper/apis/toolpiper-api/revisions/6722bf56385c?raw)