> 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. > **Info** > > **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](/developers/docs/references/content-management-api/overview), 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. > **Info** > > **Note:** For EU data residency customers, the base URL is > *[https://api.eu.contentful.com](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](/developers/docs/references/authentication#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. > **Info** > > 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](https://en.wikipedia.org/wiki/Optimistic_concurrency_control). 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. [Changing a Destination Node's type](/developers/docs/references/experience-management-api/destinations-management/destinations/destination-nodes#changing-a-nodes-type) replaces it with a new draft at `sys.version: 1`. Use the version returned by the conversion response for subsequent writes, and refresh any children or redirects whose links were updated. 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](/developers/docs/references/content-management-api/overview#api-rate-limits): **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](https://en.wikipedia.org/wiki/ISO_8601). > **Info** > > **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](/developers/docs/references/experience-delivery-api/destinations-delivery) 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: ```json { "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`.