---
title: "Move folders under a new parent (idempotent)"
method: POST
path: "/api/folders/batch-move"
tags: ["Folders"]
---

# Move folders under a new parent (idempotent)

`POST /api/folders/batch-move`

## Request

- Base URL: `https://api.engram.page`
- URL: `https://api.engram.page/api/folders/batch-move`
- Auth: HTTP bearer

Re-parents multiple folders under `target_parent_id` (or the literal `"root"` for top level) in one transaction and returns the moved count. Requires the `X-Idempotency-Key` header. Returns 404 for a missing id and 409 (with `item_id`) on a conflict or a cycle.

## Request body

- BatchMoveFoldersRequest
  - `ids` string[], required
  - `target_parent` string: Destination parent folder path (alternative to target_parent_id; "" = top level). Use this to re-parent under a derived folder that has no marker.
  - `target_parent_id` string: Parent folder UUID or "root".

## Response `200`

Moved count

- MovedCount
  - `moved` integer, required

## Other responses

- `400`: Invalid input
- `404`: Some ids not found
- `409`: Conflict
- `422`: Target path cleans to nothing

---

[API](https://skmtc.dev/engram/apis/engram-api.md) · [All operations](https://skmtc.dev/engram/apis/engram-api/llms.txt) · [OpenAPI document](https://skmtc.dev/engram/apis/engram-api/revisions/8c4c2eec29dc?raw)