Preview moving a node
/api/v1/nodes/{id}/move/previewReports what moving the node under parent_node_id would change, without moving it. blockers lists what would refuse the move, with the code and message the move answers 400 with (the schema's parent and child types, depth, a cycle, an organization boundary); when any is listed nothing else is resolved. Otherwise: subtree_size, the node and every node beneath it; identities_gaining, identities_losing and permissions, the counts per key, over everyone; people, one page of the holders whose access at the node changes (and so beneath it, since grants inside the subtree travel with it), one row per person by name, with the keys gained and lost and via, the grants behind them, and pagination. The query narrows the page and never the counts: q (name or email), direction (gains or loses), permission (one key), page and take (up to 5000, so a client can export every change in a few reads); and invites and directory_groups, the pending invitations and directory groups at nodes in the subtree, which move with it. People are named only for a reader who may see the Environment's people (people_named: env_identities.view in the Console, and production_identities.access in a production Environment; identity.view for an API key; access administration at the node for a tenant's administrator); anyone else gets the counts and an empty page, whatever the query. Resolved by the rules evaluate applies. Read-only. Send version as If-Match and parent_version in the body on the move, so it applies only to the node and the destination previewed. Gated as the move is: hierarchy.manage on the node and on the new parent. Returns 404 when the node or the parent is not found in this Environment.
Authentication
Authorization Option A JWT access token. Never send alongside X-API-Key: a request carrying both is refused.
X-API-Key Option B API key for management-tier access. Never send alongside an Authorization header: a request carrying both is refused.
Path Parameters
idstring Required Query Parameters
pagenumber Optional Page of people (1-based)
takenumber Optional People per page (1-5000, default 20)
qstring Optional Only people whose name or email contains this, ignoring case
directionenum Optional Only the people gaining access, or only those losing it
permissionstring Optional Only the people gaining or losing this permission key (with `direction`, only that side)
Request body
application/json
parent_node_idstring Required parent_versionnumber Optional The destination's `version`, as the move's preview read it: the move answers `409 version_mismatch` when the destination has changed since
Responses
application/json
data *NodeMovePreviewDto
application/json
error *ApiErrorBodyDto
application/json
error *ApiErrorBodyDto
application/json
error *ApiErrorBodyDto
application/json
error *ApiErrorBodyDto
Returned object
curl -X POST "https://auth.canopy-io.com/api/v1/nodes/value/move/preview?page=0&take=0&q=value&direction=gains&permission=value" \ -H "X-API-Key: $CANOPY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "parent_node_id": "string", "parent_version": 0 }'
{ "data": { "blockers": [ { "code": "hierarchy.reparent_cycle", "message": "string" } ], "people_named": false, "identities_gaining": 0, "identities_losing": 0, "permissions": [ { "permission": "string", "gaining": 0, "losing": 0 } ], "people": { "items": [ { "identity": { "id": "string", "first_name": "string", "last_name": "string", "name": "string", "email": "string", "avatar_url": "string" }, "gained": [ "string" ], "lost": [ "string" ], "via": [ { "role": {}, "node": {} } ] } ], "pagination": { "page": 0, "take": 0, "item_count": 0, "page_count": 0, "has_previous_page": false, "has_next_page": false } }, "node_id": "string", "parent_node_id": "string", "version": 0, "parent_version": 0, "subtree_size": 0, "invites": { "total": 0, "names": [ "string" ] }, "directory_groups": { "total": 0, "names": [ "string" ] } } }
Tell us how we can improve this guide.