Destinations Management | Documentation

In active development: The Destinations Management API is shared with design partners while it is being built out. The shape of resources and endpoints may change before general availability.

The Destinations Management API describes how published content is delivered to the front end. A Channel declares the routing contract for a class of front ends — the properties every front end of that kind must provide, and the properties included in its paths. A Destination implements that contract for one space and environment, and a tree of Destination Nodes maps individual paths to published experiences.

It is a sibling of the Content Management API, shares the same host, and uses the same authentication. If you already use the CMA, the request shape will feel familiar.

Channels are scoped to an organization. Destinations and Destination Nodes are scoped to a space and environment.

Note: For EU data residency customers, the base URL is https://api.eu.contentful.com.

Basic API information

API base URL https://api.contentful.com This is a read/write API

Authentication

The API is accessed securely via HTTPS. Clients must authenticate the requests with a Content Management API access token.

To learn about authenticating and getting your access token, refer to the Content Management API.

Updating resources

Contentful doesn’t merge changes to destinations resources, so when updating one, you must send the entire resource body. If you update a resource with a subset of properties, you will lose all existing properties not included in that update.

You can’t update any of the sys property fields, including sys.id. A Destination’s Channel is fixed when the Destination is created, so channelId must not be sent when updating one.

Updating and version locking

Like the CMA, the Destinations Management API uses optimistic locking. When updating an existing resource, you need to specify its current version with the X-Contentful-Version HTTP header. Contentful compares this version with the current version stored to ensure that a client doesn’t overwrite a resource that has since been updated. If the version changed in-between, Contentful would reject the update.

A stale version returns 409 Conflict. Fetch the resource again, reapply your change to the new version, and retry.

Header requirements vary by resource and operation:

Operation	`X-Contentful-Version`
List, read, and read tree	Not accepted
Create a Channel, Destination, or Destination Node	Not accepted
Upsert a Channel or Destination Node	Optional — omit it to create the resource, send the current version to update it
Update a Destination	Required
Delete a Channel, Destination, or Destination Node	Required
Publish or unpublish any resource	Required

API rate limits

API rate limits specify the number of requests a client can make to Contentful APIs in a specific time frame. Every request counts against a per-second rate limit.

The Destinations Management API enforces the same rate limits as the Content Management API: 7 requests per second by default. Higher rate limits may apply depending on your current plan.

When a client gets rate limited, the API responds with the 429 Too Many Requests HTTP status code and sets the value of the X-Contentful-RateLimit-Reset header to an integer specifying the time before the limit resets and another request will be accepted.

Common resource attributes

Every resource returned by the API includes a sys property. The sys object contains system-managed and resource-dependent information. At minimum sys defines the sys.type property.

During entity creation, the value of sys.id is either automatically generated or can be specified in the URL of the initial PUT request.

Note: sys metadata fields can not be changed programmatically.

Field	Type	Description
sys.type	String	Type of a resource. One of `Channel`, `Destination`, `DestinationFolderNode`, `DestinationExperienceNode`, or `DestinationRedirectNode`.
sys.id	String	Unique ID of a resource.
sys.organization	Link	Link to a Channel’s organization.
sys.space	Link	Link to a resource’s space.
sys.environment	Link	Link to a resource’s environment.
sys.channel	Link	Link to the Channel a Destination implements.
sys.destination	Link	Link to the Destination a Destination Node belongs to.
sys.version	Integer	Current version of a resource.
sys.publishedVersion	Integer	Published version of a resource.
sys.publishedCounter	Integer	Number of times a resource was published.
sys.firstPublishedAt	Date	Date and time a resource was published for the first time.
sys.publishedAt	Date	Date and time a resource was published after an update.
sys.publishedBy	Link	Link to publishing user.
sys.createdAt	Date	Date and time a resource was generated in the system.
sys.createdBy	Link	Link to creating user.
sys.updatedAt	Date	Date and time a resource was updated in the system.
sys.updatedBy	Link	Link to updating user.

Date and time format

Date and time must be formatted according to ISO 8601.

Important: When setting time, ensure to indicate timezone. With no timezone specified, UTC+0 is applied as a default.

Publishing order

Publishing follows the dependency order of the model. Publish a Channel before publishing the Destinations that reference it, and publish an Experience before publishing the Destination Node that serves it.

Publishing a Destination or a Destination Node rebuilds and uploads the delivery artifact asynchronously. A successful publish response does not guarantee that the Destinations Delivery API has picked up the new artifact yet.

Deletion runs in reverse: unpublish a resource before deleting it, and remove a Destination’s Destination Nodes before deleting the Destination.

Collection resources and pagination

The Destinations collection endpoint implements cursor-based pagination. Unlike offset-based pagination, which uses skip and limit parameters, cursor-based pagination uses opaque cursor tokens to mark the position in the dataset:

{
  "sys": { "type": "Array" },
  "limit": 100,
  "items": [
    /* individual resources */
  ],
  "pages": { "next": "bnVsbDoxMDA" }
}

The pages object contains a next key when there are further resources 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.

The response does not include a total count or a skip property. The default page size is 100 and the maximum allowed limit is 1000.