> 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. # Introduction > **Info** > > **Note**: The use of Contentful is subject to the [Fair Usage Policy](https://www.contentful.com/r/knowledgebase/fair-use/) and to ensure uninterrupted functionality of the shared-service infrastructure, adhere to [Technical Limits](https://www.contentful.com/developers/docs/technical-limits/). The Content Delivery API (CDA), available at *cdn.contentful.com*, is a read-only API for delivering content from Contentful to apps, websites and other media. Content is delivered as JSON data, and images, videos and other media as files. The API is available via a globally distributed content delivery network (CDN). The server closest to the user serves all content, which minimizes latency and especially benefits mobile apps. Hosting content in multiple global data centers also improves the availability of content. You'll need a free Contentful account and Contentful space to get started. You can sign up [here](https://www.contentful.com/sign-up/). > **Info** > > **Note:** For EU data residency customers, the Base URL is **[https://cdn.eu.contentful.com](https://cdn.eu.contentful.com)**. ## Basic API information API Base URL `https://cdn.contentful.com` *This is a read-only API* ## Authentication Any client requesting content from the CDA needs to provide an access token that has access to the environment you're requesting content from. For example, if you create an access token that only has access to the `master` environment of your space, you will not be able to use this token to access content from any other environment. You have two options to supply the access token, either as an `Authorization` request header field, or as an `access_token` URI query parameter. The CDA implements the standardized OAuth 2.0 bearer token specification already supported by many HTTP clients. You create access tokens in the *APIs* tab of each space in the Contentful web app. [Our reference guide](/references/authentication) has more details on how authentication works with Contentful. ## 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. There are no limits enforced on requests that hit our CDN cache, i.e. the request doesn't count towards your rate limit and you can make an unlimited amount of cache hits. For requests that do hit the Content Delivery API, a rate limit of **55** requests per second is enforced. 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 `X-Contentful-RateLimit-Reset` header that tells the client when it can make its next single request. The value of this header is 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. **Example** The current rate limit for a client is the default 55 per second. Client: 85 uncached requests in 1 second ``` HTTP/1.1 429 X-Contentful-RateLimit-Reset: 1 ``` Meaning: wait 1 second before making more requests. The following table lists all headers returned in every response by the Content Delivery API which give a client information on rate limiting: | Header | Description | | ------------------------------------- | ------------------------------------------------------------- | | `X-Contentful-RateLimit-Second-Limit` | The maximum amount of requests which can be made in a second. | | `X-Contentful-RateLimit-Reset` | The number of seconds until the next request can be made. | ## Common resource attributes Every resource returned by the Content Delivery API will have a `sys` property, which is an object containing system managed metadata. The exact metadata available depends on the resource type, but at minimum it defines the `sys.type` property. **Note**: None of the `sys` fields are editable and you can only specify the `sys.id` in the creation of an item (If it's not a \*space\_). Contentful defines the `sys.id` property for every resource that is not a collection. For example, a `Space` resource will have a `sys.type` and `sys.id`: ```json { "sys": { "type": "Space", "id": "yadj1kx9rmg0" } } ``` | Field | Type | Description | Applies to | | -------------------- | ------- | ---------------------------------------------------------- | ------------------------------ | | sys.type | String | Resource type. | All | | sys.linkType | String | Type of an entity the link is referring to. | Links | | sys.id | String | Unique ID of resource. | All except arrays | | sys.space | Link | Link to resource's space. | Entries, assets, content types | | sys.environment | Link | Link to a resource's environment. | Entries, assets, content types | | sys.contentType | Link | Link to entry's content type. | Entries | | sys.revision | Integer | Publish counter of the resource. | Entries, assets, content types | | sys.createdAt | Date | Date and time a resource was published for the first time. | Entries, assets, content types | | sys.updatedAt | Date | Date and time a resource was published after an update. | Entries, assets, content types | | sys.locale | String | Locale of the resource. | Entries and assets | | sys.publishedVersion | Integer | Published version of the resource | Entries, assets, content types | **Note**: The `revision` field refers to the current number of published revisions of an entry. [Find out more in the Content Management API documentation.](/references/content-management-api/overview) > **Info** > > **Sys properties - difference in meaning in Contentful APIs** > > Some of `sys` properties, while having the same label, render different kinds of data depending on the API. Please see the descriptions of these properties per API in the table below: > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > >
> Property name per API >
> CMA > > CDA > > CPA > > Description >
> firstPublishedAt > > createdAt > > \- > > Date and time a resource was published for the first time. >
> publishedAt > > updatedAt > > \- > > Date and time a resource was published after an update. >
> createdAt > > \- > > createdAt > > Date and time a resource was generated in the system. >
> updatedAt > > \- > > updatedAt > > Date and time a resource was updated in the system. >
## 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 one. The table below displays the supported date and time formatting: | Data type | Format | Examples | | ---------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------ | | Date only | "YYYY-MM-DD" | "2015-11-06" | | Date + time | "YYYY-MM-DDThh:mm:ss" "YYYY-MM-DDThh:mm:ss.sss" | "2015-11-06T09:45" | | Date + time + timezone | "YYYY-MM-DDThh:mm:ssZ" "YYYY-MM-DDThh:mm:ss±\[hh:mm]" | "2015-11-06T09:45:27Z" "2015-11-06T09:45:27+00:00" "2015-11-06T09:45:27-08:00" | ## 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. For example, `order=sys.createdAt` will order results by the time the resource was first published. > **Info** > > Don't use `skip` to iterate through an entire collection. Performance degrades as the offset grows, particularly for complex queries and deep link resolution. `skip`/`limit` is intended for random access into a bounded result set (for example, "page 3 of 20" in a UI). > > To fetch or process every item in a large collection, such as exports, analytics, migrations, or any exhaustive traversal, use [cursor pagination](#cursor-pagination) instead. ## Filter results You can use a variety of filter parameters to search and filter items in the response from collection endpoints. ### Example usage ``` name[match]=fred&sys.user.sys.id[in]=abc123,zyx987&sys.updatedAt[lt]=2018-09-01 ``` In general the format of a filter parameter is as follows: ``` field[operator]=value ``` ### Operators For each supported field, one or more operators is available. This table explains their usage: | Operator | Description | | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `eq` | The resource field exactly matches the specified value. E.g. `name[eq]=fred` (or `name=fred` for short). Maximum length for text fields is 256 characters | | `ne` | The resource field does *not* match the specified value. E.g. `name[ne]=fred` | | `match` | The resource field starts with the specified value. E.g. `name[match]=fre` | | `in` | The resource field matches at least one of the specified values in a comma separated list. E.g. `sys.user.sys.id[in]=abc123,zyx987`. Maximum length for text fields is 256 characters | | `nin` | The resource field does *not* match any of the specified values in a comma separated list. E.g. `sys.user.sys.id[nin]=abc123,zyx987` | | `exists` | The resource field is not empty if the specified value is `true`, or empty if the specified value is `false`. E.g. `sys.updatedAt[exists]=true` | | `lt` | The resource field is less than the specified value. E.g. `sys.updatedAt[lt]=2018-09-01` | | `lte` | The resource field is less than or equal to the specified value. E.g. `sys.updatedAt[lte]=2018-09-01` | | `gt` | The resource field is greater than the specified value. E.g. `sys.updatedAt[gt]=2018-09-01` | | `gte` | The resource field is greater than or equal to the specified value. E.g. `sys.updatedAt[gte]=2018-09-01` | | `all` | Returns only items whose selected field contains every value you specify in the filter | ## 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. Use cursor pagination whenever you need to traverse a whole collection, for example, exporting a space, running analytics over all entries, or processing every asset. Use offset pagination (`skip`/`limit`) only for bounded, random-access cases, such as showing a specific page of results in a UI. #### 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 ```json { "sys": { "type": "Array" }, "limit": 100, "items": [ ... ], "pages": { "next": "/spaces/:space_id/entries?pageNext=cursor_token", "prev": "/spaces/:space_id/entries?pagePrev=cursor_token" } } ``` #### 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.