---
title: "Move a folder under a new parent"
method: POST
path: "/v1/vault/folders/{id}/move"
tags: ["Vault"]
---

# Move a folder under a new parent

`POST /v1/vault/folders/{id}/move`

## Request

- Base URL: `http://localhost:9998`
- URL: `http://localhost:9998/v1/vault/folders/{id}/move`
- Auth: HTTP bearer

Reparents the folder; the whole subtree moves with it, ids stable.
Moving a folder into itself or its own subtree is 400 `invalid_move`.
Returns the moved folder as a bare tree node.

## Path parameters

- `id` string, required

## Request body

- object
  - `newParentPath` string, required: New parent folder's vault-relative path ('' for the vault root).

## Response `200`

The moved 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`: Resource 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)