Overview

Contentful’s Content Management API (CMA) helps you manage content in your spaces. To learn more about how to model your content, read our modeling guide.

NOTE: You can use the CMA to deliver and manage content, but you shouldn’t use it to deliver large amounts of content and instead use the Content Delivery API. The structure of responses from the CMA differs from the CDA as GET responses retrieve the entirety of items (i.e. all localized and unpublished content).

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 an access token.

Learn about authenticating to the CMA and get 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 content

Contentful doesn’t merge changes made to content, so when updating content, you need to send the entire body of an entry. 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 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

Contentful uses optimistic locking. When updating an existing resource, you need to specify its current version with the X-Contentful-Version HTTP header (this header is automatically set when using our official client libraries). 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.

By default the Contentful Management API enforces rate limits of 7 requests per second. Higher rate limits may apply depending on your current plan.

The following table lists all headers returned in every response by the Content Management API which give a client information on rate limiting:

Here is a part of a Contentful Management API response example showing the headers for rate limiting:

X-Contentful-RateLimit-Reset: 0
X-Contentful-RateLimit-Second-Limit: 7
X-Contentful-RateLimit-Second-Remaining: 9

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

Examples:

The current rate limits for a client are the default 7 per second.

Example 1

Client: 5 requests in 1 second

HTTP/1.1 2xx
X-Contentful-RateLimit-Reset: 0

Meaning: not rate limited. More requests are allowed.

Example 2

Client: 11 requests in 1 second

HTTP/1.1 429
X-Contentful-RateLimit-Reset: 1

Meaning: wait 1 second before making more requests.

Example 3

Client: 9000 requests in 15 minutes, 9000 requests in following 15 minutes, 9000 requests in following 15 minutes, 9000 requests in following 15 minutes

HTTP/1.1 429
X-Contentful-RateLimit-Reset: 900

Meaning: wait 15 minutes before making more requests (which frees up 9000 requests - 15 minutes later 9000 requests get freed up and so on).

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 (e.g. /environments/master/entries/my-custom-id) of the initial PUT request. The only entity which always uses generated sys.id values is spaces.

Note: sys metadata fields can not be changed programmatically.

The sys.id property is defined for every resource that is not a collection. For example, a Space resource will have a sys.type and sys.id:

1
{
2
  "sys": {
3
    "type": "Space",
4
    "id": "yadj1kx9rmg0"
5
  }
6
}

Date and time format

Date and time must be formatted according to ISO 8601.

The table below displays the supported date and time formatting:

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. For example, order=sys.createdAt will order results by the time the resource was first published.

Cursor pagination

Overview

Cursor pagination is an approach to paginating datasets in Contentful APIs. Unlike traditional offset-based pagination, which uses skip and limit parameters, cursor-based pagination uses opaque cursor tokens and dedicated next/prev links to mark the position in the dataset. This can dramatically improve performance, especially for datasets with large numbers of items.

How cursor pagination works

• Initial Request:
  Add the query parameter cursor=true to your API request, e.g.

  GET /spaces/:space_id/entries?cursor=true

  The response contains:

  • items: The current page of resources.
  • pages: Contains next (and optionally prev) URLs for paginating forward and backward.

• Paginate forward:
  Use the pages.next URL from the previous response for the next page request:

  GET /spaces/:space_id/entries?pageNext={cursor_token}

  Continue this process until the next link is omitted, which means you’ve reached the end of the dataset.

• Paginate backward: If the response contains a pages.prev link, you can fetch previous pages:

  GET /spaces/:space_id/entries?pagePrev={cursor_token}

• Consistency: All query parameters used in the initial request apart from limit are locked and encoded in the cursor token. They cannot be changed between pages.

  The limit parameter can be updated, and the new value will be persisted for subsequent pages until it’s updated again.

  GET /spaces/:space_id/entries?pageNext={cursor_token}&limit={limit}

  This can be useful when you need to adjust the page size, for example, if a page size (in bytes) exceeds the response limit.

• Total count: The response does not include a total count or a skip property. This is a key feature for performance, as the API avoids costly full counts on large datasets.

Example response

1
{
2
  "sys": { "type": "Array" },
3
  "limit": 100,
4
  "items": [ ... ],
5
  "pages": {
6
    "next": "/spaces/:space_id/entries?pageNext=cursor_token",
7
    "prev": "/spaces/:space_id/entries?pagePrev=cursor_token"
8
  }
9
}

Advantages

• Considerable performance improvements, particularly for large datasets.

If your environment contains 10s of thousands of entries or assets, consider switching to cursor pagination, it can make requests to fetch lists of entries or assets of such an environment much faster.

If you don’t paginate at all, particularly when working with CDA and you don’t need the total property from the response, we highly recommend using requests with cursor=true.

Limitations

• The “total” property is not included in the API responses. Make sure you don’t rely on it in your workflow prior to making the switch.

Enablement and access

• The feature is currently available in the CMA, CPA and CDA.

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.