Overview

In active development: The Experiences 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 Experiences Management API lets you author and manage Experience Orchestration (ExO) resources in your space — design tokens, component types, templates, experiences, fragments, optimization variants, release experiences/fragments, data types, and data assemblies.

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.

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

You access the API securely via HTTPS, and it will be available to clients authenticating with a Content Management API access token.

Learn about authenticating and getting your access token from the developer center.

Resource IDs

When creating resources, you can specify an ID or let the API generate a random ID for you. If you choose an ID yourself it must adhere to the following rules:

  • It has a length between 1 and 64 characters.

  • It only includes alphanumeric characters, dots ., hyphens - or underscores _.

Represented as a regular expression, this is /^[a-zA-Z0-9-_.]{1,64}$/.

Updating resources

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

You should always update resources in the following order:

  • Fetch current resource.

  • Make changes to the current resource.

  • Update the resource by passing the changed resource along with the current version number.

This way no unseen changes are overridden and unexpected conflicts are unlikely to occur.

Note: You can’t update any of the sys property fields, including sys.id.

Updating and version locking

Like the CMA, the Experiences 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.

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 Experiences 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.

FieldTypeDescription
sys.typeStringType of a resource.
sys.idStringUnique ID of a resource.
sys.spaceLinkLink to a resource’s space.
sys.environmentLinkLink to a resource’s environment.
sys.versionIntegerCurrent version of a resource.
sys.publishedVersionIntegerPublished version of a resource.
sys.publishedCounterIntegerNumber of times a resource was published.
sys.firstPublishedAtDateDate and time a resource was published for the first time.
sys.publishedAtDateDate and time a resource was published after an update.
sys.publishedByLinkLink to publishing user.
sys.createdAtDateDate and time a resource was generated in the system.
sys.createdByLinkLink to creating user.
sys.updatedAtDateDate and time a resource was updated in the system.
sys.updatedByLinkLink 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.

Collection resources and pagination

Contentful returns collections of resources in a wrapper object that contains extra information useful for paginating over large result sets:

1{
2  "sys": { "type": "Array" },
3  "skip": 0,
4  "limit": 100,
5  "total": 1256,
6  "items": [ /* 100 individual resources */ ]
7}

In the above example, a client retrieves the next 100 resources by repeating the same request, changing the skip query parameter to 100. You can use the order parameter when paging through larger result sets to keep ordering predictable.

API versioning

All API requests should specify a Content-Type header of application/vnd.contentful.management.v1+json.

If not specified, Contentful will route your request to the latest version of the API. This could break clients which expect the outdated API version. To be certain, always specify the Content-Type header.