1. Docs
  2. API Reference
  3. Update hierarchy schema for the active Environment

Update hierarchy schema for the active Environment

PATCH/api/v1/hierarchy-schema

Replaces the active Environment's hierarchy schema wholesale with the supplied node_types, allowed_children map, max_depth (1–16), and root_node_type (which must be one of node_types). The update targets the Environment resolved from the principal context. Pass the Environment's current version in the If-Match header for optimistic locking — a stale value returns 409. The persisted schema is re-read and returned in the response.

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.

Headers

  • if-match required
  • If-Match

    Optimistic-lock token. Pass the `version` you read from the Environment — request fails 409 when the row has moved on.

Request body

application/json

node_typesstring[] Required

Allowed node types (e.g. ['organization', 'region', 'team']). Order is informational, not structural — parent/child rules are governed by `allowed_children`.

allowed_childrenobject Required

Map from node type to allowed child node types. Empty array means leaf-only.

max_depthnumber Required

Maximum nesting depth (root counts as depth 1).

range 1–16

root_node_typestring Required

Node type used when the root node is auto-created. Must be one of `node_types`.

Responses

application/json

  • dataHierarchySchemaResponseDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

Returned object

HierarchySchemaResponseDtoView all properties on this resource
Request
curl -X PATCH "https://auth.canopy-io.com/api/v1/hierarchy-schema" \
  -H "if-match: value" \
  -H "If-Match: value" \
  -H "X-API-Key: $CANOPY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "node_types": [
      "string"
    ],
    "allowed_children": {
      "organization": [
        "region"
      ],
      "region": [
        "team"
      ],
      "team": []
    },
    "max_depth": 0,
    "root_node_type": "string"
  }'
Response
{
  "data": {
    "node_types": [
      "string"
    ],
    "allowed_children": {},
    "max_depth": 0,
    "root_node_type": "string"
  }
}
 Related endpoints
GETGet hierarchy schema for the active Environment
 Was this page helpful?

Tell us how we can improve this guide.

Canopy