# (NEW!) Create Metadata Cascade

Create a metadata cascade — its level schema and initial value tree — as one merged resource, in a single call. This replaces what was previously two separate writes (create the attribute, then create its value map); there is no longer a separate map/attribute split at all.

Defaults:
- nameVisible defaults to true.

Business Rules:
- levels must contain at most 4 entries. Each attributeId must reference an existing, single-select controlled-vocabulary attribute.
- values may be omitted to create an empty cascade. Nesting depth via children must not exceed levels.length (and therefore can never exceed 4). No two nodes in the submitted tree may share the same id.
- searchField is optional. Omitted, it is generated server-side. Supplied, it is used as-is and the cascade is created as featured (featured: true). Either way it is permanently fixed thereafter.
- A duplicate name/searchField is rejected with 409.

The user submitting the request must have the Metadata Template Management admin privilege.

Endpoint: POST /metadata/cascades
Version: 1.5
Security: ApiKeyAuth, BasicAuth

## Header parameters:

  - `Authorization` (string, required)
    Provided by Authentication Token creation operation.

  - `Content-Type` (string, required)
    Enum: "application/json"

## Request fields (application/json):

  - `name` (string, required)
    Display name for the new cascade.
    Example: "Region Cascade"

  - `searchField` (string)
    Optional. When supplied, the cascade is created as featured, using this value as its permanent search field slug instead of a server-generated one.
    Example: "region_cascade"

  - `nameVisible` (boolean)
    Whether the cascade name is visible when rendered on an asset. Defaults to true.
    Example: true

  - `levels` (array, required)
    Level schema for the cascade. Maximum 4 entries. Each attributeId must reference an existing, single-select controlled-vocabulary attribute.

  - `levels.order` (integer, required)
    Zero-based level position.

  - `levels.attributeId` (string, required)
    Id of the existing, single-select controlled-vocabulary attribute backing this level.
    Example: "a29f3e1c-7b4d-4f8a-9c2e-5d1b8f6a3c70"

  - `values` (array)
    Initial value tree. May be omitted to create an empty cascade and populate values later via update. id is client-generated so a multi-level tree can be submitted in one request. Nesting depth via children must not exceed levels.length (and therefore can never exceed 4). No two nodes in the submitted tree may share the same id.

  - `values.id` (string, required)
    Client-generated id for this value node, unique within the submitted tree.
    Example: "f3a8c1e5-9d24-4b7a-8e6f-1c3a9d5e2b74"

  - `values.name` (string, required)
    Display value.
    Example: "North America"

  - `values.children` (array)
    Nested child values at the next level. Omit or leave empty for a leaf node.

## Response 201 fields (application/json):

  - `id` (string)
    Unique ID of the cascade.
    Example: "b7e41f2a-6c9d-4a17-8f3b-2d5c8a0e3f61"

  - `name` (string)
    Display name of the cascade.
    Example: "Region Cascade"

  - `searchField` (string)
    System-generated slug. Permanent once created.
    Example: "region_cascade"

  - `levels` (array)
    Ordered levels, fixed at creation. Always present here — unconditional, unlike the list endpoint where it's only included via ?include=levels.

  - `levels.attributeId` (string)
    Id of the controlled-vocabulary attribute backing this level's dropdown values.
    Example: "a29f3e1c-7b4d-4f8a-9c2e-5d1b8f6a3c70"

  - `levels.attributeName` (string)
    Denormalized display name of the backing attribute.
    Example: "Continent"

  - `levels.order` (integer)
    Zero-based level position; kept as an explicit field rather than implied by array order, since asset metadata can store level references out of order.

  - `nameVisible` (boolean)
    Whether the cascade name is visible when rendered on an asset.
    Example: true

  - `featured` (boolean,null)
    System-assigned. null if never set. Blocks deletion when true.

  - `createdBy` (string)
    User-profile id of the cascade's creator.
    Example: "8f2a5c91-4e6d-4b83-9a17-6c0d3e8b2f45"

  - `createdEpoch` (integer)
    Unix timestamp (ms) of creation.
    Example: 1770714900000

  - `createdDate` (string)
    ISO 8601 creation date.
    Example: "2026-02-10T09:15:00Z"

  - `lastUpdatedBy` (string)
    User-profile id of the last user to update the cascade.
    Example: "8f2a5c91-4e6d-4b83-9a17-6c0d3e8b2f45"

  - `lastUpdatedEpoch` (integer)
    Unix timestamp (ms) of the last update.
    Example: 1771432800000

  - `lastUpdatedDate` (string)
    ISO 8601 last-updated date.
    Example: "2026-02-18T16:40:00Z"

  - `usedIn` (object)
    Where the cascade is currently referenced. A cascade's only direct relationship is being used as a column inside a Table. metadataGroups is a derived, transitive rollup of every group reached through that table's own group membership (Table → group). metadataTemplates is a further derived, transitive rollup of every template reached through that group's own template membership (group → template).

  - `usedIn.metadataTables` (array)
    Tables that directly use this cascade as a column.

  - `usedIn.metadataTables.id` (string)
    Example: "e91a4c7d-3f8b-4e26-9a1d-7c5b0e9f2a83"

  - `usedIn.metadataTables.name` (string)
    Example: "Store Locations Table"

  - `usedIn.metadataGroups` (array)
    Groups that transitively reach this cascade through a table that uses it.

  - `usedIn.metadataTemplates` (array)
    Templates that transitively reach this cascade through a table that uses it.

  - `values` (array)
    Full nested value tree, returned untruncated — always present here (unconditional, same as levels; the list endpoint only includes it via ?include=values). Depth is bounded at 4 levels, but breadth is not — a level with hundreds of sibling values can still make this a large payload.

  - `values.id` (string)
    Value node id.
    Example: "f3a8c1e5-9d24-4b7a-8e6f-1c3a9d5e2b74"

  - `values.name` (string)
    Display value.
    Example: "North America"

  - `values.source` (string,null)
    Present only when this level's attribute is a Dynamic Controlled Vocabulary (a CV composed from other CVs) — holds the search field of the underlying source CV this value was copied from. null for a value sourced from an ordinary controlled vocabulary. System-computed only; never client-supplied.

  - `values.children` (array)
    Nested child values at the next level. Empty array for a leaf node.

## Response 400 fields (application/json):

  - `status` (string)
    Example: "error"

  - `message` (string)

## Response 401 fields (application/json):

  - `status` (string)
    Example: "error"

  - `message` (string)

## Response 403 fields (application/json):

  - `status` (string)
    Example: "error"

  - `message` (string)

## Response 409 fields (application/json):

  - `status` (string)
    Example: "error"

  - `message` (string)