---
title: "Move or rename a file or directory"
method: POST
path: "/v1/filesystem/move-file"
tags: ["Files"]
---

# Move or rename a file or directory

`POST /v1/filesystem/move-file`

## Request

- Base URL: `http://localhost:9998`
- URL: `http://localhost:9998/v1/filesystem/move-file`
- Auth: HTTP bearer

Atomic `rename(2)` when source and destination share a volume.
Creates missing parent directories of `to`. `collision` decides what
happens when `to` exists (default `fail` → 409); `replace` refuses to
clobber a directory tree. Both endpoints must pass the workspace
symlink-escape guard.

## Request body

- object
  - `from` string, required
  - `to` string, required
  - `collision` 'fail' | 'replace' | 'keep_both' | 'merge'

## Response `200`

Moved

- object
  - `from` string, required
  - `to` string, required

## Other responses

- `404`: Source not found
- `409`: Destination exists and collision is fail

---

[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)