API Changes

The new Usage API replaces the legacy periodic usage endpoints and is available now.

What is changing

The following two CMA endpoints are deprecated as of August 18, 2026 and will be removed on February 28, 2027:

• GET /organizations/:organization_id/organization_periodic_usages
• GET /organizations/:organization_id/space_periodic_usages

Why we made this change

The legacy endpoints report on a limited set of metrics with fixed monthly granularity. The new Usage API consolidates all consumption-based reporting into a single, consistent API surface that supports daily and monthly granularity, custom date ranges, and all metrics including API calls, asset bandwidth, AI actions, and Functions. It is the same API powering the usage dashboards in the Contentful web app and will continue to expand as new usage data becomes available. It gives you self-serve visibility into your consumption data so you can reconcile invoices, identify traffic spikes, and automate usage monitoring. The legacy endpoints will not receive further updates.

What replaces them

Two new CMA endpoints are available now:

• GET /metric returns aggregated time series data for any usage metric. It supports daily granularity for up to 31 days and monthly granularity for up to 12 months, with results grouped by space or API type.
• GET /usages-detailed provides per-asset bandwidth breakdowns to help identify specific files driving high traffic.

Impact on your integration

If you are currently calling either legacy endpoint, those calls will stop working and return 410 Gone after February 28, 2027.

Key dates

• August 18, 2026: The legacy endpoints are deprecated and will no longer receive updates or support.
• February 28, 2027: The legacy endpoints are removed and will no longer respond to requests.

Action required

Migrate to the new Usage API before February 28, 2027. For step-by-step migration instructions, including a mapping from legacy parameters to new ones, see the Usage API migration guide.

Starting February 15th, 2027, we will update how space roles are returned from the Content Management API (CMA) when listing roles within a space.

The /spaces/{spaceId}/roles endpoint will switch from offset-based pagination to cursor-based pagination.

What's changing

Responses from the space roles list endpoint will include a pages object with cursor-based navigation links (next, previous) instead of the current total and skip fields.

The limit parameter continues to be supported.

What you need to do

If your integration iterates through space roles using the skip query parameter, you will need to update it to use the new pageNext and pagePrev cursor parameters instead.

Please review our updated API documentation to ensure your integration handles the new response structure before the rollout date.

Starting 14.08.2026, we will update how user data is returned from the Content Management API (CMA) when fetching users within a space. API responses for user data will become role-based:

• Admin users will continue to receive full responses, with no changes.
• Non-admin users will receive limited user information in the following endpoints:
  • Get all users in a space.
  • Get all Space Members in a space.

The reduced data set for non-admin users is already reflected in our public documentation and will be enforced from the date above.

What you need to do

If your implementation uses API tokens associated with non-admin users to fetch data from these endpoints, you should expect less information in responses than before. Please update your integrations accordingly to handle the reduced payload.

Contentful has added locale-based publishing support to the Content Delivery API (CDA) and GraphQL Content API. The X-Contentful-Locale-Based-Publishing: true request header makes delivery requests follow the publishing status of each locale instead of relying only on the publishing status of the entry.

This update helps teams keep draft or incomplete localized content out of production, coordinate multilingual launches more confidently, and use the same publishing expectations across the CDA and GraphQL Content API.

Send the X-Contentful-Locale-Based-Publishing: true request header with CDA or GraphQL Content API requests to enable locale-based publishing behavior:

• Published locales - The APIs check entry.sys.fieldStatus and resolve content only for locales that are marked as published.
• Unpublished locales - The CDA returns a 404 response for an unpublished locale. The GraphQL Content API returns null for the field result.
• Fallback locales - Fallbacks can still be used to resolve content, but they don't change the publishing status of the requested locale. A published fallback locale doesn't make an unpublished locale visible.
• Added locales - After a locale is added to a space, entries must be republished before that locale is returned by the CDA.
• Entry-level publishing - For customers using entry-level publishing only, adding the header doesn't change API behavior. The header is backward compatible and locale-based publishing is planned to become the default behavior in a later release.

For more information, refer to Content Delivery API and GraphQL Content API.

Starting May 21st, 2026, the Content Management API supports a new token, fields._displayField, in the select= query parameter on GET /spaces/{space_id}/environments/{environment_id}/entries. When the token is included, the API resolves each entry's display field from its content type and returns the value under the field's real name.

The token is composable with the standard select operator: combine it with any other tokens you would normally pass to select=, or use it on its own. Unlike standard field selectors, fields._displayField does not require content_type=, so it can resolve the display field across entries from different content types in a single call.

Examples

• select=fields._displayField returns the resolved display field for each entry.
• select=sys,fields._displayField returns sys plus the resolved display field for each entry.
• select=fields.body,fields._displayField combined with content_type= returns the explicit field, and the resolved display field. The display field is not duplicated if it already appears in the select list.
• select=sys,fields,fields._displayField returns the full entry. The token is a no-op when the bare fields selector is present.

Entries whose content type has no displayField, or whose display field has no value, are returned without fields.

This change is additive. Existing select= behavior is unchanged.

We’ve enforced HTTPS for Content Delivery API. HTTP requests are no longer served directly. They now receive an HTTP 301 (Moved Permanently) and a Location header with the equivalent HTTPS URL.

This aligns with our documented security posture (Transport Layer Security for all API traffic) and reduces the risk of insecure traffic being used in production integrations.

What you need to do:

• Ensure your Content Delivery API base URL is set to HTTPS.
• If you observe unexpected 301 responses, update the client to follow redirects or switch to HTTPS directly.

The Content Delivery API and the GraphQL API now return the x-contentful-ratelimit-second-limit response header. The value is the per-second request limit configured for your space, so you can monitor the limit the same way on every response.

Details

• The x-contentful-ratelimit-second-limit is included on HTTP 200 and HTTP 429 responses.
• For HTTP 429 responses, x-contentful-ratelimit-reset is also returned along with x-contentful-ratelimit-second-limit. This is consistent with how rate limiting is signaled when a request is rejected for exceeding the limit.

We’ve enforced HTTPS for the Content Preview API. HTTP requests are no longer served directly. They now receive an HTTP 308 (Permanent Redirect) to the equivalent HTTPS URL.

This aligns with our documented security posture (Transport Layer Security for all API traffic) and reduces the risk of insecure traffic being used in production integrations.

What you need to do:

• Ensure your Content Preview API base URL is set to HTTPS.
• If you observe unexpected 308 responses, update the client to follow redirects or switch to HTTPS directly.

Starting April 21st, 2025, we are switching to RE2 as our regular expression engine, specifically the RE2JS npm package. This will enforce stricter validations for regular expressions in the Content Management API (CMA). From this date, you will no longer be able to publish entries with any regular expressions match or prohibit rules that are not accepted by the regular expression engine.

The previous date for this change was March 21st, 2025, however, to accommodate our customers' needs, we are pushing the date. For more information, see the previous changelog, and the Regular Expression (Regex) page.

Starting March 21st 2025, we are switching to the regular expression engine RE2. This will enforce stricter validations for regular expressions in the Content Management API (CMA). From this date, you will no longer be able to publish entries with any regular expressions match or prohibit rules that are not accepted by the regular expression engine.

We are switching to the RE2 engine as it provides more security and better performance compared to the regular engine.

What you need to do:

To continue publishing entries with offending regular expression validation rules, you need to rewrite these regular expressions and check if they are accepted by the new engine.

One way to do that is to try it out on this Playground, or you can make sure it does not include anything listed in the unsupported rules of RE2.

Starting February 17th, 2025, the GraphQL Content API will support the Embargoed assets feature for relevant customers. This enhancement extends the functionality of embargoed assets, allowing authenticated access to restricted assets directly through GraphQL queries.

Embargoed assets restrict public access to content by requiring that all requests include a dynamically generated signature. When enabled, these assets are served from the ***.secure.ctfassets.net domain.

For more details, see the Embargoed Assets page and the Asset keys section of the GraphQL API page.

On February 17th, 2025, we are releasing an update to resolve an issue where the query complexity was miscalculated when the limit argument was set to 0.

After this update:

When the limit is omitted or explicitly set to 0, a default limit of 100 will apply.

This change ensures consistent behaviour across all Contentful APIs, including GraphQL API, Content Delivery API (CDA), and Content Preview API (CPA).

What you need to do:

We recommend reviewing any queries that use a limit of 0 to ensure they align with this updated behaviour. This only affects a very small number of our customers who have also been notified via email.

See GraphQL Content API - Complexity Limits for more details.

The Content Management API (CMA) now supports marking taxonomy validations as required on content type metadata.

Once a particular taxonomy validation has been marked required for a given content type, any entry of that content type will be checked on publish to determine if the entry has taxonomy concepts assigned which fulfill the required validation(s) from the relevant content type.

To make use of this feature, a new required boolean property on the link to the taxonomy concept or concept scheme can be sent in POST, PUT, and PATCH requests for content types.

Once the feature is live, this new property will always be returned on the content type and defaulted to false.

For more information on the Content Type endpoint, see the documentation.

We are announcing a further postponement of the enforcement of stricter validation for required fields in the Content Management API (CMA) to accommodate our customers during the upcoming busy holiday and retail periods.

The new enforcement date will now be 21st January 2025.

After this date, entries with any required fields left empty will not be publishable, even if these fields are hidden in the field editor. If a field’s validation is set as both disabled: true and required: true but is left empty, a validation error will occur. We will then reveal the hidden fields so that a value can be input.

Thank you for your understanding as we aim to make this transition as seamless as possible. Please reach out if you have questions or need support in preparing for this update.

For more information about the upcoming change and how to migrate, see the Validations for hidden and required fields page and the Content Management API page.

Starting November 14th 2024, we are implementing stricter validation for required fields in the Content Management API (CMA). From this date, entries with any required fields left empty cannot be published, even if these fields are hidden in the field editor. If a field’s validation is set as both disabled: true and required: true but is left empty, a validation error will occur.

Scheduled publish actions that meet this criterion will also be impacted.

What you need to do:

To continue publishing entries with hidden fields, change the validation of these fields to optional (required: false).

Starting with March 20th, you will no longer be able to save an entry through the Content Management API (CMA) with a locale that was not previously configured, even if the X-Contentful-Skip-Transformation header is present.

After March 14th, 2024, the generated GraphQL type for ResourceLink fields will change from a type to an interface and for each field a new type will be generated that implements the ResourceLink interface. The name of the generated type will be derived from the content type name and the field name. For example, if an content type LandingPage has a reference field headline, the new type name will be LandingPageHeadline. If LandingPage has a multi-reference field called testimonials, the generated type will be LandingPageTestimonialsCollection. Additionally, the type field in ResourceSys type will be removed.

The following is an example of a content type LandingPage that has two ResourceLink fields, headline and testimonials and it illustrates the change in the generated schema:

Old schema

the new schema:

Starting with Monday, August 29th 2022, when the schema generation fails, our GraphQL API returns a 422 HTTP status code instead of a 500 HTTP status code.

Our GraphQL API can currently fail on three scenarios during the generation of your schema:

• Colliding type names
• Colliding field names
• Reserved field names

For more information on how schemas are generated, see the Schema generation section on the GraphQL Content API page.

Before the fix, these scenarios led to an error with a HTTP status code of 500 for any request until the user took specific action to fix the issue. As this is considered an issue on the client side, a HTTP status code of 422 is returned from August 29th.

Starting with Monday, July 13th, the behaviour of the localization feature changes as follows:

• When using the locale=* query parameter with unlocalized fields, the API endpoints for entries will no longer return field values related to locales different to the environment default one.

Note that the current behavior of returning all the locales for a non-localized field was a bug that emerged when the user modified a previously localized field to unlocalized.

Consider the following example comparing the two behaviors:

Given an entry with two fields, where the first is localized and the second was set to unlocalized after being initially localized, the API returns:

On Wednesday 19th January, we will deprecate the boilerplate-api endpoint, which was formerly used to access pre-configured Contentful projects. The related contentful-cli “contentful boilerplate” command will also be deprecated at the same time.

These resources can now be accessed more easily from Contentful's Github. Therefore, to keep our APIs streamlined we are deprecating the unneeded endpoint.