move_nodes
Reposition or reparent existing design nodes while preserving their IDs. Specify a sibling or target parent to reorder layers, and get updated affected parent lists.
Instructions
Move one or more existing nodes. Preserves node identity (IDs stay the same), so any references you are holding continue to work. Prefer this over duplicate+delete or rewriting HTML when you just want to reposition or reparent existing layers.
Each move uses one of two shapes:
Sibling-relative: { nodeId, before: siblingId } or { nodeId, after: siblingId }. The destination parent is inferred from the sibling.
Parent-absolute: { nodeId, parentId, index? }. The node is placed at the given index under parentId, or appended if index is omitted. index is clamped to [0, childCount] — use 0 for first. Pass parentId: 'root' as a shortcut for the top-level page root as a parent.
Use shape sibling-relative shape 1 when you already know a neighbor; use parent-absolute shape 2 when you want to move into a specific parent (or to the end of one).
Notes:
Moves apply sequentially; later moves in the same batch see earlier changes.
For flex/flow parents this changes visual order. For freeform parents this changes stacking (last child renders on top) and does not move the node's world position.
When moving to a new parent, Paper may adjust layout-related styles (width/height intents like filling available space) may be adjusted so the node does not collapse to zero size in the new parent.
Cannot move the root. Cannot target a node that cannot have children. Cannot move a node under itself or any of its own descendants. For before/after, the sibling cannot be the moved node itself. Returns resolved parentId and index for each successful move, plus affectedParents — the post-batch children list of every parent whose order changed (both sources and destinations, deduplicated). Use affectedParents to refresh your mental model of the tree without a follow-up get_children.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| moves | Yes | Move operations, applied sequentially. Each operation sees the updated tree from prior operations. | |
| fileId | No | Optional. The Paper file ID this call should act on. Pass it to reliably target a specific file when several are open at once (e.g. multiple agents from the same session working in parallel). Omit to use the most recently opened file in the session. |