Introduction

The Destinations Delivery API, available at xdn.contentful.com, is a read-only API that returns the published routing tree of a Destination as a flattened sitemap and resolves Destination paths or Destination Node IDs to hydrated Experiences. Experience resolution can include optional personalization input.

Destinations, their Destination Nodes, and the Channel they implement are authored and published with the Destinations Management API.

Basic API information

API base URL https://xdn.contentful.com This is a read-only API

Authentication

The API is securely accessed via HTTPS. Pass a bearer token in the Authorization header or use the access_token query parameter.

Do not expose tokens in client-side source code. Query-string tokens can appear in logs and browser history, so prefer the Authorization header where possible.

Environment scope

The route doesn’t include an environment segment, so the API always resolves the master environment. Selecting another environment through a path or query parameter isn’t supported.

Sitemap response

The published form of a Destination is a flattened sitemap — one entry per routable path, each naming the experience served at that path. The nesting of Destination Folder Nodes is resolved away, so a client reads a single list rather than walking a tree.

The response has the following shape:

{
  "property": {
    "sys": { "type": "Destination" }
  },
  "paths": {
    "sys": { "type": "Array" },
    "limit": 100,
    "items": [
      {
        "sys": { "type": "DestinationExperienceNode" },
        "path": "/products",
        "experienceUrn": "crn:contentful:::experience:spaces/$self/environments/$self/experiences/productIndex"
      }
    ],
    "pages": { "next": "bnVsbDoxMDA" }
  }
}

Each entry in paths.items includes the following fields:

Experience resolution

The API can resolve a published Experience by absolute path or Destination Node ID. A successful resolution returns the hydrated Experience and child paths at the next depth level for lazy loading. If the path belongs to a Destination Redirect Node, the response contains the redirect target instead.

Use the cacheable GET endpoint for an unpersonalized Destination Node lookup. Use POST when resolving by path or when supplying personalization profile and event data.

Pagination

The paths collection is cursor-paginated. The default page size is 100 and the maximum allowed limit is 1000.

The paths.pages object contains a next key when there are further paths to fetch, and a prev key when you have paged forward. Pass the value back as the pageNext or pagePrev query parameter to retrieve that page. Treat the tokens as opaque, and do not send pageNext and pagePrev in the same request.

Publish propagation

Publishing a Destination or one of its Destination Nodes rebuilds and uploads the delivery artifact asynchronously. A successful publish response from the Destinations Management API does not guarantee that this API has observed the new artifact yet, so poll for the paths you expect rather than reading once.

A 404 Not Found immediately after a first publish can mean the artifact is still being written. A persistent 404 means no artifact has been uploaded for that Destination.

After a Destination is unpublished, the API stops serving its previous sitemap.