Skip to content

Collection trees and entry parents

Collection trees and entry parents

Collection metadata does not describe the page hierarchy. Request a site-specific collection tree with:

{"action":"get","resource_type":"collection","handle":"pages","site":"default","include_tree":true}

The response adds site and tree to collection. Collection listing includes only collections the current user may view, before totals and pagination. Editors receive basic editing metadata; collection configuration remains an administrator operation.

To create or update an entry under a parent, pass data.parent to statamic-entries. Use an entry ID from the same collection and site, or null for the top level. Omit the field to leave the existing parent unchanged.

{"action":"update","collection":"pages","id":"CHILD_ID","site":"default","data":{"parent":"PARENT_ID"}}

Alternatively, move a branch through statamic-structures:

{"action":"update","resource_type":"collection","handle":"pages","site":"default","data":{"entry":"CHILD_ID","parent":"PARENT_ID"}}

The structures router is discoverable with search_tools and callable through execute_tools. This operation moves the existing subtree; it does not accept a replacement tree or mix a move with collection settings. Sibling-position editing is outside this API. The returned parent is the saved parent; top-level entries return null, including entries immediately below a configured collection root. Creating the first entry in a collection with a root also accepts parent: null. An existing root accepts null as an unchanged parent; moving it under another entry or assigning itself as its parent is refused.

Moves require collection reorder rights, permission to edit the moved entries, an accessible site and parent, the entries/structures resource policies and both entries:write and structures:write scopes. Tree reads require both read scopes. Invalid IDs, cross-site/collection parents, cycles, root moves, excessive depth and URI collisions fail explicitly. Existing authentication and confirmation behavior is unchanged. Field deny lists also apply to parent metadata and tree reads, including for administrators and local CLI callers. Both domains' field policies apply to tree data. If an update combines fields and a parent, collision checks use the proposed field values before saving content, including fields used by a custom route.

For published entries with revisions enabled, submit a parent-only move separately from content edits. Moving the structure takes effect immediately; it must not be silently combined with an unpublished content working copy.

MCP moves use a collection/site cache lock, detect a tree file changed during validation, and verify the resulting parent. Content and structure files are not a cross-file transaction; the MCP lock does not serialize CP or external file writes. Full-tree replacement and concurrent external editing are outside the operation's guarantees.