Move file or folder

move_node

Through	Form
HTTP	`POST https://api.markdownbrain.ai/v1/nodes/move`
MCP	tool `move_node`
CLI	`mdbrain call move_node`

Move a file or folder under a new parent folder. Name the node with path or node_id, and the destination with new_parent_path ("" = workspace root) or new_parent_id (null = workspace root). By default (update_links, true unless you pass false) every link you can see that the change would break is rewritten to the new place, rooted at the brain (/folder/file.md), in the documents that link here and in what moves; the result's links_updated says how many links were rewritten (rewritten) of how many found (of), in how many documents, and names any document left as it was in failed, with why. A document that cannot be updated never undoes the change. With update_links: false, links that point at this node stop working. The result's inbound_links says how many documents linked here before the change (documents, and up to 20 sources by path), or is null if they could not be counted.

Who may call it: agents and people.

Writes: yes.

Arguments

Name	Type	Required	Travels in	Description
`workspace_id`	string	no	JSON body	Only needed to disambiguate a `path`, or alongside `node_id`
`node_id`	string	no	JSON body	file_node id of the node to move — or use `path`
`path`	string	no	JSON body	Workspace-relative path of the node to move
`new_parent_id`	string or null	no	JSON body	Destination folder id, or null for the workspace root
`new_parent_path`	string	no	JSON body	Destination folder path; "" means the workspace root
`update_links`	boolean	no	JSON body	Rewrite the links this change would break so they keep working (default true)

Success

200 with application/json.

Example request

curl -X POST https://api.markdownbrain.ai/v1/nodes/move \
  -H "Authorization: Bearer $MDBRAIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path":"specs/12-onboarding.md","workspace_id":"00000000-0000-4000-8000-000000000010","new_parent_path":"research"}'

mdbrain call move_node \
  --path specs/12-onboarding.md \
  --workspace-id 00000000-0000-4000-8000-000000000010 \
  --new-parent-path research

Example response

Written from the code rather than captured from a call.

{
  "node_id": "00000000-0000-4000-8000-000000000102",
  "new_parent_id": "00000000-0000-4000-8000-000000000108",
  "name": "12-onboarding.md",
  "inbound_links": {
    "documents": 1,
    "sources": [
      "specs/09-pricing.md"
    ]
  },
  "links_updated": {
    "rewritten": 1,
    "of": 1,
    "documents": 1,
    "failed": []
  }
}

Refusals

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