> This page is for API Reference.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://contentful.com/developers/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://contentful.com/developers/docs/_mcp/server.

# Upsert a Destination Node by ID

PUT https://api.contentful.com/spaces/{spaceId}/environments/{environmentId}/destinations/{destinationId}/nodes/{nodeId}
Content-Type: application/vnd.contentful.management.v1+json

Updates a Destination Node by ID, or creates a new one with the specified ID if the Destination Node does not exist. Omit `X-Contentful-Version` to create; send the current version to update.

Include a top-level `type` field set to `DestinationFolderNode`, `DestinationExperienceNode`, or `DestinationRedirectNode`. Requests without `type` are rejected. Experience and redirect nodes can be saved as unassigned drafts, but require `experience` or `redirectTo`, respectively, before publishing.

Include `parent` when updating an existing node. Omit it only when creating a node at the Destination root.

To change between folder and experience nodes, send the target `type`, the current `X-Contentful-Version`, and a complete body preserving the existing parent and path. The node, its descendants, and any redirects targeting it must be unpublished. Success returns **200 OK** with the same ID and `sys.version` reset to `1`. Changes to or from redirect nodes are unsupported. See [Changing a node's type](/developers/docs/references/experience-management-api/destinations-management/destinations/destination-nodes#changing-a-nodes-type) for requirements and client refresh behavior.

For property fields, path validation, and home nodes, see [Node properties and paths](/developers/docs/references/experience-management-api/destinations-management/destinations/destination-nodes#node-properties).

Reference: https://contentful.com/developers/docs/references/experience-management-api/destinations-management/destinations/destination-nodes/upsert-destination-node

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Path parameters

- `spaceId` (string, required) — ID of the space.
- `environmentId` (string, required) — ID of the environment.
- `destinationId` (string, required) — ID of the Destination.
- `nodeId` (string, required) — ID of the Destination Node.

### Headers

- `X-Contentful-Version` (string, optional) — Current version of the resource, taken from `sys.version`. Omit the header to create a resource with the specified ID; send the current version to update an existing one.

### Body (application/vnd.contentful.management.v1+json)

This endpoint expects a DestinationNodeRequest.

- `DestinationNodeRequest`
  - `type`: `DestinationFolderNode`
    - `properties` (list of DestinationNodePathPropertyRequest, required)
    - `name` (string, optional)
    - `parent` (DestinationNodeParent, optional) — Parent of this Destination Node. Optional when creating a node; omitting it attaches the node to the Destination root. Required when updating an existing node, including when changing its type.
  - `type`: `DestinationExperienceNode`
    - `properties` (list of DestinationNodePathPropertyRequest, required)
    - `experience` (DestinationExperienceLink, optional) — Resource link to the experience this Destination Node serves.
    - `name` (string, optional)
    - `parent` (DestinationNodeParent, optional) — Parent of this Destination Node. Optional when creating a node; omitting it attaches the node to the Destination root. Required when updating an existing node, including when changing its type.
  - `type`: `DestinationRedirectNode`
    - `properties` (list of DestinationNodePathPropertyRequest, required)
    - `name` (string, optional)
    - `parent` (DestinationNodeParent, optional) — Parent of this Destination Node. Optional when creating a node; omitting it attaches the node to the Destination root. Required when updating an existing node, including when changing its type.
    - `redirectTo` (DestinationRedirectTarget, optional) — Link to another Destination Node in the same Destination. The target must exist and must not be the redirect node itself.

## Response

### 200

OK - Destination Node updated

- `DestinationNode`
  - Destination Folder Node: DestinationFolderNode
  - Destination Experience Node: DestinationExperienceNode
  - Destination Redirect Node: DestinationRedirectNode

## Types

### DestinationNodePathPropertyRequest

- `path` (string, required) — Local path segment containing only ASCII letters, numbers, hyphens, underscores, and dots. Nonempty segments must not consist only of dots. Use an empty string for the home node. See [Paths](/developers/docs/references/experience-management-api/destinations-management/destinations/destination-nodes#paths) for validation and existing-path compatibility.
- `type` ("Path", optional) — Optional property discriminator. Omit it or set it to `Path`; responses include `type` set to `Path`.

### DestinationNodeParent

Parent of this Destination Node. Optional when creating a node; omitting it attaches the node to the Destination root. Required when updating an existing node, including when changing its type.

- `sys` (DestinationNodeParentSys, required)

### DestinationExperienceLink

Resource link to the experience this Destination Node serves.

- `sys` (DestinationExperienceLinkSys, required)

### DestinationRedirectTarget

Link to another Destination Node in the same Destination. The target must exist and must not be the redirect node itself.

- `sys` (DestinationRedirectTargetSys, required)

### DestinationFolderNode

A Destination Node that groups other Destination Nodes without serving or redirecting to an experience.

- `parent` (DestinationNodeParent, required) — Parent of this Destination Node. Optional when creating a node; omitting it attaches the node to the Destination root. Required when updating an existing node, including when changing its type.
- `properties` (list of DestinationNodePathProperty, required)
- `sys` (DestinationFolderNodeSys, required)
- `name` (string, optional)

### DestinationExperienceNode

A Destination Node that serves an experience.

- `parent` (DestinationNodeParent, required) — Parent of this Destination Node. Optional when creating a node; omitting it attaches the node to the Destination root. Required when updating an existing node, including when changing its type.
- `properties` (list of DestinationNodePathProperty, required)
- `sys` (DestinationExperienceNodeSys, required)
- `experience` (DestinationExperienceLink, optional) — Resource link to the experience this Destination Node serves.
- `name` (string, optional)

### DestinationRedirectNode

A Destination Node that redirects to another Destination Node in the same Destination.

- `parent` (DestinationNodeParent, required) — Parent of this Destination Node. Optional when creating a node; omitting it attaches the node to the Destination root. Required when updating an existing node, including when changing its type.
- `properties` (list of DestinationNodePathProperty, required)
- `sys` (DestinationRedirectNodeSys, required)
- `name` (string, optional)
- `redirectTo` (DestinationRedirectTarget, optional) — Link to another Destination Node in the same Destination. The target must exist and must not be the redirect node itself.

### DestinationNodeParentSys

- `type` ("Link", required)
- `linkType` (enum, required)
  - Allowed values: `Destination`, `DestinationFolderNode`, `DestinationExperienceNode`, `DestinationRedirectNode`
- `id` (string, required)

### DestinationExperienceLinkSys

- `type` ("ResourceLink", required)
- `linkType` ("Contentful:Experience", required)
- `urn` (string, required) — Contentful Resource Name of the experience.

### DestinationRedirectTargetSys

- `type` ("Link", required)
- `linkType` (enum, required)
  - Allowed values: `DestinationExperienceNode`, `DestinationFolderNode`, `DestinationRedirectNode`
- `id` (string, required)

### DestinationNodePathProperty

Routing path supplied for the Channel's `Path` Destination Node property.

- `type` ("Path", required)
- `path` (string, required) — Stored local path segment for this Destination Node. Existing paths remain readable even if they do not meet the current write rules. See [Paths](/developers/docs/references/experience-management-api/destinations-management/destinations/destination-nodes#paths).

### DestinationFolderNodeSys

- `destination` (Link, required) — Link to another Contentful resource.
- `environment` (Link, required) — Link to another Contentful resource.
- `id` (string, required)
- `space` (Link, required) — Link to another Contentful resource.
- `type` ("DestinationFolderNode", required)
- `createdAt` (string, optional) — Date and time the resource was created.
- `createdBy` (Link, optional) — Link to another Contentful resource.
- `firstPublishedAt` (string, optional) — Date and time the resource was published for the first time.
- `publishedAt` (string, optional) — Date and time the resource was last published.
- `publishedBy` (Link, optional) — Link to another Contentful resource.
- `publishedCounter` (integer, optional) — Number of times the resource has been published.
- `publishedVersion` (integer, optional) — Version of the resource that is currently published.
- `updatedAt` (string, optional) — Date and time the resource was last updated.
- `updatedBy` (Link, optional) — Link to another Contentful resource.
- `version` (integer, optional) — Current version of the resource. Send this value as `X-Contentful-Version` when updating, deleting, publishing, or unpublishing.

### DestinationExperienceNodeSys

- `destination` (Link, required) — Link to another Contentful resource.
- `environment` (Link, required) — Link to another Contentful resource.
- `id` (string, required)
- `space` (Link, required) — Link to another Contentful resource.
- `type` ("DestinationExperienceNode", required)
- `createdAt` (string, optional) — Date and time the resource was created.
- `createdBy` (Link, optional) — Link to another Contentful resource.
- `firstPublishedAt` (string, optional) — Date and time the resource was published for the first time.
- `publishedAt` (string, optional) — Date and time the resource was last published.
- `publishedBy` (Link, optional) — Link to another Contentful resource.
- `publishedCounter` (integer, optional) — Number of times the resource has been published.
- `publishedVersion` (integer, optional) — Version of the resource that is currently published.
- `updatedAt` (string, optional) — Date and time the resource was last updated.
- `updatedBy` (Link, optional) — Link to another Contentful resource.
- `version` (integer, optional) — Current version of the resource. Send this value as `X-Contentful-Version` when updating, deleting, publishing, or unpublishing.

### DestinationRedirectNodeSys

- `destination` (Link, required) — Link to another Contentful resource.
- `environment` (Link, required) — Link to another Contentful resource.
- `id` (string, required)
- `space` (Link, required) — Link to another Contentful resource.
- `type` ("DestinationRedirectNode", required)
- `createdAt` (string, optional) — Date and time the resource was created.
- `createdBy` (Link, optional) — Link to another Contentful resource.
- `firstPublishedAt` (string, optional) — Date and time the resource was published for the first time.
- `publishedAt` (string, optional) — Date and time the resource was last published.
- `publishedBy` (Link, optional) — Link to another Contentful resource.
- `publishedCounter` (integer, optional) — Number of times the resource has been published.
- `publishedVersion` (integer, optional) — Version of the resource that is currently published.
- `updatedAt` (string, optional) — Date and time the resource was last updated.
- `updatedBy` (Link, optional) — Link to another Contentful resource.
- `version` (integer, optional) — Current version of the resource. Send this value as `X-Contentful-Version` when updating, deleting, publishing, or unpublishing.

### Link

Link to another Contentful resource.

- `sys` (LinkSys, required)

### LinkSys

- `type` ("Link", required)
- `linkType` (string, required)
- `id` (string, required)

## Examples

**Request**

```json
{
  "type": "DestinationFolderNode",
  "properties": [
    {
      "path": "products"
    }
  ]
}
```

**Response**

```json
{
  "name": "name",
  "parent": {
    "sys": {
      "id": "id",
      "linkType": "Destination",
      "type": "Link"
    }
  },
  "properties": [
    {
      "path": "products",
      "type": "Path"
    }
  ],
  "sys": {
    "createdAt": "createdAt",
    "createdBy": {
      "sys": {
        "id": "id",
        "linkType": "linkType",
        "type": "Link"
      }
    },
    "destination": {
      "sys": {
        "id": "id",
        "linkType": "linkType",
        "type": "Link"
      }
    },
    "environment": {
      "sys": {
        "id": "id",
        "linkType": "linkType",
        "type": "Link"
      }
    },
    "firstPublishedAt": "firstPublishedAt",
    "id": "id",
    "publishedAt": "publishedAt",
    "publishedBy": {
      "sys": {
        "id": "id",
        "linkType": "linkType",
        "type": "Link"
      }
    },
    "publishedCounter": 1,
    "publishedVersion": 1,
    "space": {
      "sys": {
        "id": "id",
        "linkType": "linkType",
        "type": "Link"
      }
    },
    "type": "DestinationFolderNode",
    "updatedAt": "updatedAt",
    "updatedBy": {
      "sys": {
        "id": "id",
        "linkType": "linkType",
        "type": "Link"
      }
    },
    "version": 1
  }
}
```