# Rename file or folder

`rename_node`

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

Rename a file or folder. Name it with `path` or with `node_id` — exactly one of the two. 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 — or use `path` |
| `path` | string | no | JSON body | Workspace-relative path of the node to rename |
| `name` | string | yes | JSON body | The new name alone, with no folder in it; to move the node, use [`move_node`](/docs/operations/move_node) |
| `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

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

```sh
mdbrain call rename_node \
  --path specs/12-onboarding.md \
  --workspace-id 00000000-0000-4000-8000-000000000010 \
  --name 12-first-run.md
```

## Example response

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

```json
{
  "node_id": "00000000-0000-4000-8000-000000000102",
  "name": "12-first-run.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](/docs/errors).