> 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-staging.ferndocs.com/developers/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://contentful-staging.ferndocs.com/developers/docs/_mcp/server.

> **Info**
>
> **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](/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.

> **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

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](/references/authentication#the-content-management-api).

## 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](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.

## 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](/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.                                        |
| sys.id               | String  | Unique ID of a resource.                                   |
| sys.space            | Link    | Link to a resource's space.                                |
| sys.environment      | Link    | Link to a resource's environment.                          |
| 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.

## Collection resources and pagination

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

```json
{
  "sys": { "type": "Array" },
  "skip": 0,
  "limit": 100,
  "total": 1256,
  "items": [ /* 100 individual resources */ ]
}
```

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.