1. Docs
  2. API Reference
  3. Preview moving a node

Preview moving a node

POST/api/v1/nodes/{id}/move/preview

Reports 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

Bearer TokenAuthorization Option A

JWT access token. Never send alongside X-API-Key: a request carrying both is refused.

API KeyX-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)

min 1

takenumber Optional

People per page (1-5000, default 20)

range 1–5000

qstring Optional

Only people whose name or email contains this, ignoring case

max length 200

directionenum Optional

Only the people gaining access, or only those losing it

one of "gains" · "loses"

permissionstring Optional

Only the people gaining or losing this permission key (with `direction`, only that side)

max length 200

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

  • dataNodeMovePreviewDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

Returned object

Request
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
  }'
Response
{
  "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"
      ]
    }
  }
}
Related endpoints
GETList hierarchy nodes (scoped, paged)
POSTCreate a hierarchy node
GETList the hierarchy as parent edges
GETGet a hierarchy node
PATCHUpdate a hierarchy node
DELETEDelete a hierarchy node
GETGet subtree from a node
GETGet ancestor chain for a node
GETGet direct children of a node
POSTMove (reparent) a node
POSTPreview deleting a node
GETList identities at a node
GETList who holds a permission at a node
GETGet identity summary for a node
Was this page helpful?

Tell us how we can improve this guide.