Destination Nodes

Destination nodes form the routing tree of a destination. Every create and upsert request must include an explicit top-level type field to select one of three node types:

Requests with a missing or unsupported type return 422 Unprocessable Entity. The API does not infer the node type from the presence of experience or redirectTo.

Experience and redirect nodes can be saved as unassigned drafts. An experience node requires experience before publishing, and a redirect node requires redirectTo before publishing. Publishing an unassigned node returns 422 Unprocessable Entity. Folder nodes accept neither reference, experience nodes accept only experience, and redirect nodes accept only redirectTo.

Node properties

Every request to create or update a destination node accepts the following common fields, regardless of the node type:

The selected node type determines which reference the request accepts:

A destination node response identifies the node type through sys.type. Each variant contains properties, parent, and sys, together with name, experience, or redirectTo when assigned.

Paths

If the Channel declares a node property of type Path, supply its value in properties as { "path": "products" }. The property discriminator type is optional in requests: { "type": "Path", "path": "products" } is also valid. Responses include type set to Path.

Each properties[].path is a single local path segment. Create and upsert requests accept only ASCII letters (A–Z, a–z), numbers (0–9), hyphens (-), underscores (_), and dots (.). Nonempty segments must not consist only of dots. Whitespace, Unicode, slashes, other punctuation, and dynamic placeholder syntax are rejected.

Invalid writes return 422 Unprocessable Entity with a field error at properties.<index>.path.

To build a route with multiple segments, create a node at products, then add a child with path set to shoes to resolve /products/shoes. The API joins parent and child segments with / when resolving paths. Resolved paths must be unique within the Destination.

Use an empty string ("") for the home path, which resolves to /.

Existing stored paths remain readable and are not automatically rewritten. When updating a node whose path no longer meets these rules, submit a valid replacement path, even if the update changes another field. Publish the node through the usual workflow to deliver the changed route.

For example, create an experience node with this request body:

{
  "type": "DestinationExperienceNode",
  "properties": [{ "path": "products" }],
  "experience": {
    "sys": {
      "type": "ResourceLink",
      "linkType": "Contentful:Experience",
      "urn": "crn:contentful:::experience:spaces/$self/environments/$self/experiences/productIndex"
    }
  }
}

Write operations are validated against the entire destination tree, not only the destination node in the request. Contentful rejects any operation that would:

• Create a duplicate resolved path.
• Assign the home path to more than one destination node.
• Set a redirect target to a missing node, the redirect node itself, or a node in another Destination.
• Violate the integrity of the destination tree.

There is no endpoint that lists destination nodes. Use Get the Destination Node tree for a Destination to enumerate them, or keep the IDs returned by create and upsert requests.

Changing a node’s type

Use Upsert a Destination Node by ID to change a folder into an experience node, or an experience node into a folder. Changes to or from redirect nodes are unsupported.

Unpublish the node, all its descendants, and any redirects targeting it first, starting with the leaves. Send the current X-Contentful-Version and a complete body for the target type, preserving the existing parent and path properties. Move the node or change its path in a separate update. For example, convert a folder at articles into an unassigned experience node:

{
  "type": "DestinationExperienceNode",
  "name": "Articles",
  "parent": {
    "sys": { "type": "Link", "linkType": "Destination", "id": "site" }
  },
  "properties": [{ "path": "articles" }]
}

You can supply experience when converting to an experience node. Omit it when converting to a folder.

The operation preserves the node ID and location, updates direct children’s parent links and incoming redirects’ target links, and returns 200 OK. The replacement is a new draft with sys.version reset to 1, fresh creation metadata, and no publication history. Relinked children and redirects receive new versions. Use the returned version for your next write and refresh the affected nodes.

Conversion requires update permission on the existing node and create permission for the target type. A missing or stale version returns 409 Conflict. Unsupported transitions, published nodes, or a changed parent or path return 422 Unprocessable Entity with DestinationNodeTypeChangeNotAllowed, DestinationNodeTypeChangeRequiresUnpublished, or DestinationNodeTypeChangeLocationMismatch, respectively.

Destination Node

Create a new Destination Node

Get a Destination Node by ID

Upsert a Destination Node by ID

Delete a Destination Node by ID

Publishing

Publish a Destination Node

Unpublish a Destination Node