Update hierarchy schema for the active Environment

PATCH

/api/v1/hierarchy-schema

Authentication

Bearer Token Authorization
JWT access token
API Key X-API-Key
API key for management-tier access

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

node_typesstring[]*
Allowed node types (e.g. ['organization', 'region', 'team']). Order is informational, not structural — parent/child rules are governed by `allowed_children`.
allowed_childrenany object*
Map from node type to allowed child node types. Empty array means leaf-only.
max_depthnumber*
Maximum nesting depth (root counts as depth 1).
root_node_typestring*
Node type used when the root node is auto-created. Must be one of `node_types`.

Code samples

cURL

JavaScript

Python

curl -X PATCH "https://api.canopy.dev/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"
  }'

const response = await fetch("https://api.canopy.dev/api/v1/hierarchy-schema", {
  method: "PATCH",
  headers: {
    "if-match": "value",
    "If-Match": "value",
    "X-API-Key": "$CANOPY_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "node_types": [
      "string"
    ],
    "allowed_children": {
      "organization": [
        "region"
      ],
      "region": [
        "team"
      ],
      "team": []
    },
    "max_depth": 0,
    "root_node_type": "string"
  }),
});

const data = await response.json();

import requests

response = requests.patch(
    "https://api.canopy.dev/api/v1/hierarchy-schema",
    headers={
    "if-match": "value",
    "If-Match": "value",
    "X-API-Key": "$CANOPY_API_KEY",
    "Content-Type": "application/json"
    },
    json={
        "node_types": [
            "string",
        ],
        "allowed_children": {
            "organization": [
                "region",
            ],
            "region": [
                "team",
            ],
            "team": [],
        },
        "max_depth": 0,
        "root_node_type": "string",
    },
)

data = response.json()

package main

import (
	"bytes"
	"encoding/json"
	"net/http"
)

func main() {
	payload := map[string]interface{}{
		"node_types": []interface{}{
			"string",
		},
		"allowed_children": map[string]interface{}{
			"organization": []interface{}{
				"region",
			},
			"region": []interface{}{
				"team",
			},
			"team": []interface{}{},
		},
		"max_depth": 0,
		"root_node_type": "string",
	}
	body, _ := json.Marshal(payload)

	req, _ := http.NewRequest("PATCH", "https://api.canopy.dev/api/v1/hierarchy-schema", bytes.NewBuffer(body))
	req.Header.Set("if-match", "value")
	req.Header.Set("If-Match", "value")
	req.Header.Set("X-API-Key", "$CANOPY_API_KEY")
	req.Header.Set("Content-Type", "application/json")

	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

200 Hierarchy schema updated

{
  "node_types": [
    "string"
  ],
  "allowed_children": {},
  "max_depth": 0,
  "root_node_type": "string"
}

application/json

node_typesstring[]*
allowed_childrenany object*
max_depthnumber*
root_node_typestring

401 Invalid or expired token

403 This token is not authorized for this endpoint (wrong principal type — e.g., admin token on identity-only endpoint, or vice versa)

409 Version mismatch — the resource was modified since the version supplied in If-Match. Refresh and retry.

Returned object

The HierarchySchemaResponseDto object View all properties on this resource

On this page