Content Management API


Contentful's Content Management API (CMA) helps you manage content in your spaces. To learn more about how to model your content, read our modelling 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

This is a read/write API


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

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 SDKs). 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 and a per hour rate limit.

By default the Contentful Management API enforces rate limits of 10 requests per second and 36000 requests per hour. 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:

Header Description
X-Contentful-RateLimit-Hour-Limit The maximum amount of requests which can be made in an hour.
X-Contentful-RateLimit-Hour-Remaining The remaining amount of requests which can be made until the next hourly reset.
X-Contentful-RateLimit-Second-Limit The maximum amount of requests which can be made in a second.
X-Contentful-RateLimit-Second-Remaining The remaining amount of requests which can be made until the next secondly reset.
X-Contentful-RateLimit-Reset The number of seconds until the next request can be made.

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

X-Contentful-RateLimit-Hour-Limit: 36000
X-Contentful-RateLimit-Hour-Remaining: 35891
X-Contentful-RateLimit-Reset: 0
X-Contentful-RateLimit-Second-Limit: 10
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 larger than 0 specifying the time before one of the two limits resets and another request will be accepted. If the client is rate limited per second, the header will return 1, which means the next second. If the client is rate limited per hour, the next reset will be determined like this: Every request which was made in the last hour gets counted in one of four 15 minute buckets. Every time a request comes in, the API calculates how many seconds remain until the sum of all bucket counts will be below the hourly limit.


The current rate limits for a client are the default 10 per second and 36000 per hour.

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 has 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 field when creating an item (as long as it's not a Space).

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

  "sys": {
    "type": "Space",
    "id": "yadj1kx9rmg0"
Field Type Description Applies to
sys.type String Type of resource. All String Unique ID of resource. All except arrays Link Link to resource's space. Entries, assets, content types
sys.contentType Link Link to entry's content type. Entries
sys.publishedCounter Integer Number of times resource was published. Entries, assets, content types
sys.publishedVersion Integer Published version of resource. Entries, assets, content types
sys.version Integer Current version of resource. Entries, assets, content types
sys.firstPublishedAt Date Time resource was first published. Entries, assets, content types
sys.createdAt Date Time resource was created. Entries, assets, content types
sys.createdBy Link Link to creating user. Entries, assets, content types
sys.publishedAt Date Time resource was published. Entries, assets, content types
sys.publishedBy Link Link to publishing user. Entries, assets, content types
sys.updatedAt Date Time resource was updated. Entries, assets, content types
sys.updatedBy Link Link to updating user. Entries, assets, content types

Collection resources and pagination

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

  "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, for example, order=sys.createdAt, when paging through larger result sets to keep ordering predictable.

API versioning

All API requests should specify a Content-Type header of application/

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.



Spaces collection

Spaces are containers for content types and content, and API clients can fetch data from one or more spaces. You can be a member of multiple organizations, and owner and admin roles in the organization can create spaces in organizations.

When you sign up to Contentul for the first time, you create a new organization. When you're invited to an existing organization, you become a member of that organization.

Note: If you have a single organization, any space you create will be automatically associated with that organization. If you're an admin or an owner in multiple organizations you need to pass the ID of the organization with the X-Contentful-Organization header that you want to create the space in.

Get all spaces an account has access to

Create a space

Create a new space, specifying attributes in the request body.


Get a space

Update a space name

The X-Contentful-Organization header is optional if an account belongs to one organization. Attributes are sent in the body of the request as a JSON payload, and you need to set the X-Contentful-Version to the Contentul API version you are using.

Delete a space

You delete an existing space by issuing a DELETE request to /spaces/ID. Deleting a space will remove all its resources, including content types, entries and assets. This action can not be undone.


Organizations are the top level entity in Contentfuls hierarchy, consisting of spaces, users and a subscription plan, which defines the limits for the Organization. They allow the management of projects with separate pricing as well as an additional permission system, which manages users' roles within the Organization.

Organizations collection

Get all organizations an account has access to

Content types

Defining a content type is a fundamental step in powering your applications with Contentful. A content type consists of a set of fields and other information, read this guide to learn more about modelling your content.

Content type collection

Get all content types of a space

Create a content type

Whilst it's possible to create content types with POST, it's strongly discouraged.

When you use this endpoint, the API will automatically generate an ID for the created content type and return it with the response.

Using the method outlined below allows you to control the ID of the created content type. This is important for content type IDs as they are often used as parameters in code.

Content type

Create/update a content type

Use this endpoint to create a new content type with the specified ID, or to update a specific content type using its ID.

Note: When updating an existing content type, you need to specify the last version of the content type you are updating with X-Contentful-Version.


When creating or updating a content type, you can add or remove validations to the fields in the content type schema by specifying the validations property of a field.

Validation Description Applicable to Example
linkContentType Takes an array of content type ids and validates that the link points to an entry of that content type. Links to entries {"linkContentType": ["post","doc","product"]}
in Takes an array of values and validates that the field value is in this array. Text, Symbol, Integer, Number {"in": ["General", "iOS", "Android"]}
linkMimetypeGroup Takes a MIME type group name and validates that the link points to an asset of this group. Links to assets {"linkMimetypeGroup": ["image"]}
size Takes min and/or max parameters and validates the size of the array (number of objects in it). Arrays, Text, Symbol {"size": { "min": 5, "max": 20}}
range Takes min and/or max parameters and validates the range of a value. Number, Integer {"range": { "min": 5, "max": 20}}
regexp Takes a string that reflects a JS regex and flags, validates against a string. See JS reference for the parameters. Text, Symbol {"regexp": {"pattern": "^such", "flags": "im"}}
unique Validates that there are no other entries that have the same field value at the time of publication. Symbol, Integer, Number {"unique": true}
dateRange Validates that a value falls within a certain range of dates. Date {"dateRange": {"min": "2017-05-01","max": "2020-05-01"}}
assetImageDimensions Validates that an image asset is of a certain image dimension. Links to assets {"assetImageDimensions": {"width": {"min": 100,"max": 1000},"height": {"min": 200,"max": 2300}}}
assetFileSize Validates that an asset is of a certain file size. Links to assets {"assetFileSize": {"min": 1048576,"max": 8388608}}

Note: Validations will take effect after the content type has been activated and existing entries will not be validated until they are re-published.

To remove a specific validation, update the content type leaving that validation out of the field's validations collection. To remove all the validations applied to a field, update the content type schema removing the validations property.

Changing field IDs

You can change the ID of a content type field in the Contentful Web App. The API will return different data after this change, and this might break your existing code base. Read more about managing changes to content structure in our multiple environments guide.

Omitting fields

If you have fields in your content type and entries you don't want to distribute to end users (e.g. workflow states), you can omit fields from the CDA and CPA responses. To do so, update the content type with the omitted property set to true in the chosen field and activate it.

The field will still be available as part of the CMA responses and the Web App but skipped in the CDA and CPA. To revert this, repeat this but with omitted set to false.

Deleting fields

To delete fields you no longer need, first, omit the field you're targeting for deletion and activate the content type. This step is mandatory to avoid accidental data loss. It allows you to try whether your client applications can handle the deletion and provides an easy way to revert that change.

Once you have confirmed it's safe to delete the field, update your content type with the corresponding field removed from the payload, or with the deleted property set to true on the content type field you intend to delete. The deletion becomes final after you once again activate the content type. This action is permanent and cannot be undone.

Get a single content type

Delete a content type

Before you can delete a content type you need to deactivate it.

Content type activation

Activate a content type

Deactivate a content type

Activated content type collection

Get all activated content types of a space

Retrieves the activated versions of content types, ignoring any changes made since the last activation.

Editor interface

An editor interface represents the look and feel of content type fields in the web app and are tightly coupled to a specific content type.

Editor interface

An editor interface is a singleton resource of a content type, that means that there can only be one editor interface per content type at a time. It is created automatically on the first publish of a content type and updated when a content type field is added, removed or changed.

Note: Cascading updates happen when the content type is published. As the editor interface is created on the server side, it's not possible to create an editor interface manually via an HTTP request.

The API will return a 404 response if there is no editor interface for the requested content type. This typically happens when the content type was not yet published or if it was created before the automatic editor interface creation feature was added (June 20, 2016). (Re-)Publishing the content type should fix both scenarios.

Get the editor interface

Update the editor interface

You can use this endpoint to update an existing editor interface. You will need to specify its last version with X-Contentful-Version.

UI Extensions

UI Extensions allow you to customize and extend the functionality of the Contentful Web App's entry editor. Extensions can be simple user interface controls, such as a dropdown, or more complex micro applications such as our Markdown editor.

Getting started with UI extensions is a three steps process:

  • Craft the HTML, CSS and Javascript that integrate your extension. Take a look to our knowledgebase article to know more about how to build UI extensions: Extending the Contentful web app.

  • Create an extension resource using the Management API.

  • Pick an editor interface and update the configuration of one of the fields, setting its widgetId property to the id of your UI extension.

An extension resource describes to which fields your extension can be applied and where its code can be found. The following is a list of the properties of an extension resource:

Property Required Type Description
name yes String Extension name
fieldTypes yes Array[Object] * Field types where an extension can be used
src ** String URL where the root HTML document of the extension can be found
srcdoc ** String String representation of the extension (e.g. inline HTML code)
sidebar no Boolean Controls the location of the extension. If true it will be rendered on the sidebar instead of replacing the field's editing control

* Valid field types are:

  • {type: "Symbol"}

  • {type: "Text"}

  • {type: "Integer"}

  • {type: "Number"}

  • {type: "Date"}

  • {type: "Boolean"}

  • {type: "Object"}

  • {type: "Link", linkType: "Asset"}

  • {type: "Link", linkType: "Entry"}

  • {type: "Array", items: {type: "Symbol"}}

  • {type: "Array", items: {type: "Link", linkType: "Entry"}}

  • {type: "Array", items: {type: "Link", linkType: "Asset"}}

** One of src or srcdoc has to be present:

  • Use srcdoc if you want to host the extension code in Contentful. Note that extensions hosted in Contentful have a size limit of 200KB.

  • Use src if you host the extension yourself. Note that on this case your extension must be hosted on a HTTPS domain with CORS enabled.

Extensions collection

Get all extensions of a space

Create an extension


Use this endpoint to create a new extension with a specified ID, or to update a specific extension via its ID. When updating an existing extension, you need to specify the last version of the extension you are updating with X-Contentful-Version.

Create/update an extension

Get a single extension

Delete an extension


Entries collection

Entries represent text content in a space, and the data structure of an entry must adhere to a certain content type.

Get all entries of a space

Create an entry

Before you can create an entry you need to create and activate a content type as outlined above.

When creating a new entry, you need to pass the ID of the desired content type as the X-Contentful-Content-Type header and pass the field data as a JSON payload.

When using this endpoint, an ID will be automatically generated for the created entry and returned in the response.


Create/update an entry

Use this endpoint to create a new entry with a specified ID, or to update a specific entry via its ID. When updating an existing entry, you need to specify the last version of the entry you are updating with X-Contentful-Version.

When creating a new entry, you need to pass the ID of the entry's desired content type as the X-Contentful-Content-Type header. For updating an entry, passing the ID of the entry's content type is not required.

Get a single entry

Delete an entry

Entry publishing

After publishing the entry, it will be available via the Content Delivery API.

Publish an entry

Unpublish an entry

Entry archiving

You can only archive an entry when it's not published.

Archive an entry

Unarchive an entry

Beta Uploads

The Upload API, available at, provides Contentful SDKs with a direct file upload service. You can upload any binary data (including images, videos and text files) and associate the uploaded files with different Assets within a Space.

The Upload API enables the uploading of files to remote storage. To complete an upload, the uploaded file must be associated with an Asset and that asset must be processed. If the association and processing steps are not executed successfully within 24 hours after uploading, the file and its metadata will expire and be deleted from the storage area. The expiration date of the file is indicated in the API response data as expiresAt.

You can associate an Upload resource with more than one Asset and/or locale

Uploading a file

To upload a file, you send a POST request to the create upload endpoint with the binary data in the request body, and include Content-Type: application/octet-stream in the request headers. Depending on the size of your file, a success response may take some time to return. Once the upload finishes, you will receive an Upload resource in the response body.

Associating an upload with an asset

When the upload request is successful you will receive an Upload resource containing an upload_id within the field that references the uploaded file. You need to use the upload_id to associate the Upload resource with an Asset.

To associate an Upload resource with an Asset, you need to pass upload_id to the asset creation end point of the CMA with the following structure:

  "fields": {
      "title": {
          "en-US": "My cute cat pic"
      "file": {
          "en-US": {
              "contentType": "image/png",
              "fileName": "cute_cat.png",
              "uploadFrom": {
                  "sys": {
                    "type": "Link",
                    "linkType": "Upload",
                    "id": "<use of an upload resource response here>"

Maximum file size

The maximum file size should not exceed 1000MB per uploaded asset. See our Fair Usage Policy for more information. If you try to upload a larger file you will receive a Request Timeout error from the API.


The current version of the Upload API doesn't support resumability. If you encounter an error during the upload process, you need to begin the process from the beginning. It's the client's responsibility to take recovery actions in case of an error.

Upload resource

The JSON structure for an Upload has the following structure:

"sys": {
    "id": "73DfxdBnwyhQNy95A8dvSf",
    "type": "Upload",
    "createdAt": "2017-02-21T07:49:25.000Z",
    "expiresAt": "2017-02-23T00:00:00.000Z",
    "space": {
        "sys": {
            "type": "Link",
            "linkType": "Space",
            "id": "qa65bkvd5q1q"
    "createdBy": {
        "sys": {
            "type": "Link",
            "linkType": "User",
            "id": "1QaAgxMYKvdas32K4v319F"

Beta Upload a file

NOTE: The API base URL for this action is

Uploads a file to temporary file storage. Include the binary data you want to send in the request body, and Content-Type: application/octet-stream in the headers.

Creating an upload resource

Beta Retrieving an upload

NOTE: The API base URL for this action is

Retrieves an unmodified image. This is the same URL from an asset's file.url field, containing the token ids and image name.

Retrieve an upload

Beta Deleting an upload

NOTE: The API base URL for this action is

Deletes a file from temporary data storage and all the metadata associated with the given upload_id.

Note: This action can not be undone.

By default, all uploaded files are automatically deleted after 24 hours starting from when first upload request is issued.

Delete an upload


Assets collection

Assets represent files in a space. An asset can be any file, including an image, a video, an audio file, or PDF. Assets are usually attached to entries with links.

You can localize assets by providing separate files for each locale. Assets which are not localized provide a single file under the default locale.

Creating an asset requires three steps and API calls:

  1. Create an asset.

  2. Process an asset.

  3. Publish an asset.

Get all assets of a space

Create an asset

When using this endpoint, an ID will be automatically generated for the created asset and returned with the response.

Published assets collection

Get all published assets of a space

Retrieves the published versions of all assets in a space.


Create/update an asset

Use this endpoint to create a new asset with a specified ID, or update an existing asset with its ID.

Note: When updating an existing asset, you need to specify the last version you have of the asset with X-Contentful-Version.

Get a single asset

Delete an asset

Asset processing

Asset processing happens asynchronously, the call will not block other calls until it has finished.

Process an asset

Asset publishing

After publishing the asset, it will be available via the Content Delivery API.

Publish an asset

Unpublish an asset

Asset archiving

You can only archive an asset when it's unpublished.

Archive an asset

Unarchive an asset


Locales allow you to define translatable content for assets and entries. A locale includes the following properties:

  • name: A human readable identifier for a locale. For example, 'British English'.

  • code: An identifier used to differentiate translated content in API responses. For example, 'en-GB'.

  • fallbackCode: The code of the locale to use if there is no translated content for the requested locale. For example, en-US. You can set it to null if you don't want a default locale. This can only be set via the API, and not with the Web app or SDKs.

Locale collection

Get all locales of a space

The locales endpoint returns a list of all created locales. One will have the flag default set to true and is the locale used in the CDA, and you specified no other locale in the request.

Create a locale

Use this endpoint to create a new locale for the specified space. You cannot create two locales with the same locale code.

Field locales

Create a field locale

Use this endpoint to create locales for specific fields. You need to send data for all fields, even those you are not updating.


Get a locale

This endpoint returns a single locale and its metadata.

Update a locale

Use this endpoint to update existing locales in the specified space.

Note: Changing the code of a locale changes the responses for upcoming requests, which might break your existing code. Changes to the code property of locales used as a fallback are not allowed. You have to first ensure that the locale is not used as a fallback by any other locale before changing its code.

A space's default locale is permanent. This means you cannot change a locale's default property.

Deleting a locale

This endpoint deletes an existing locale. It's not possible to recover from this action, all content associated with this specific locale will be deleted and cannot be recreated by creating the same locale again.

Deleting a locale used as a fallback is not allowed. You first have to ensure that a locale is not used as a fallback before being able to delete it.

Search parameters

You can add search parameters to your query, read the reference documentation for the Content Delivery API for a full list of search parameters supported. The CMA does not support the include and locale parameters.


Webhooks notify a person or service when content has changed by calling a preconfigured HTTP endpoint. You can use this for notifications, static site generators or other forms of post-processing sourced from Contentful.


Every webhook request includes the following predefined headers:

Header Name Value
X-Contentful-Topic ContentManagement.[Type].[Action]
X-Contentful-Webhook-Name Webhook's name
Content-Type application/

Consuming services can use the X-Contentful-Topic header to determine the type of the payload included in the webhook call without looking into it. The topics depend on various actions which are described in the concepts section.

The X-Contentful-Topic header can have the following values:
  • ContentManagement.ContentType.create
  • ContentManagement.ContentType.publish
  • ContentManagement.ContentType.unpublish
  • ContentManagement.ContentType.delete
  • ContentManagement.Entry.create
  • ContentManagement.Entry.auto_save
  • ContentManagement.Entry.archive
  • ContentManagement.Entry.unarchive
  • ContentManagement.Entry.publish
  • ContentManagement.Entry.unpublish
  • ContentManagement.Entry.delete
  • ContentManagement.Asset.create
  • ContentManagement.Asset.auto_save
  • ContentManagement.Asset.archive
  • ContentManagement.Asset.unarchive
  • ContentManagement.Asset.publish
  • ContentManagement.Asset.unpublish
  • ContentManagement.Asset.delete

The Content-Type header has the application/ value as many web frameworks and their middleware components only automatically parse a request body if the content-type header is application/json, and thus require additional configuration to parse request bodies with a different content-type header.

Besides these headers, you can configure webhooks to be called with a set of additional headers of your choice. When creating or updating a webhook, you can provide a list of headers that will be included in successive calls to that webhook.

For example assume that:

  • One of your entries has just been published.

  • The name of your webhook is 'Notify subscribers'.

  • You have defined two custom headers, X-Notify: subscribers and Authentication: subscribers.

The webhook would be called with the following set of headers:

X-Contentful-Topic: ContentManagement.Entry.publish
X-Contentful-Webhook-Name: Notify subscribers
Authentication: subscribers


The payload received by a webhook will change depending on the action type:

  • For Publish it will receive the latest published version. The same payload as the CDA with the exception that the payload for Entries and Assets will contain all locales, e.g. instead of will be fields['en-US'].name.

  • For Unpublish and Delete it will receive a deletion object. In the case of Entries, the deletions are extended with the id of their Content Type.

  • For Auto Save, Archive, Unarchive and Create it will receive the latest draft version at the time the webhook was triggered. That's the same payload as the one available through the Management API.

Error handling

Contentful will use the HTTP response status code of the webhook call to decide whether it succeeded or failed:

  • Success: The webhook responded with an HTTP status code < 300.

  • Error: The webhook responded with an HTTP status code >= 300.

In case of an error with a status code >= 500, the webhook will periodically retry its request with increasing delays up to a maximum of 3 attempts.

Webhooks collection

Get all webhooks of a space

Create a webhook


Create/update a webhook

Get a single Webhook

Delete a webhook

Webhook calls

You often need to analyze the exact request and response payloads and headers to verify that the setup is correct or to diagnose issues. To help with this, some API endpoints are available that expose this information.

Webhook call overview

This call returns a list of the most recent webhook calls made, their status, possible errors, and the target URL.

Get an overview of recent calls

Webhook call details

The call details provide detailed information about the outgoing request and the response, including headers, body and possible errors. Request and response body are currently truncated at 500kb and 200kb respectively.

Get the webhook call details

Webhook health

The health endpoint provides an overview of recently successful webhook calls:

Get webhook health


Creating custom roles allows an administrator to restrict the access of users to certain resources. Roles follow a whitelisting approach, which means that you need to define everything a user is allowed to do. A role contains a name, description, permissions and policies.

Permissions can be basic rules which define whether a user can read or create content types, settings and entries. You can also create policies to allow or deny access to resources in fine-grained detail. With these polices you can, for example, limit read access to only entries of a specific content type or write access to only certain parts of an entry (e.g. a specific locale).

The following constraints are supported.


This constraint evaluates if all conditions are true. The value is an array of other constraints.

For example, to limit a user to a particular content type:

{"and": [
    { "equals": [{ "doc": "sys.type" }, "Entry"] },
    { "equals": [{ "doc": "" }, "2PqfXUJwE8qSYKuM0U6w8M"] }


This constraint compares an entity's system metadata against a specific value. Note that fields of an entry or an asset are not currently supported, only system metadata. This is a basic constraint and typically used to ensure the type of a document or to match entries of a content type.


This constraint inverts the result of its value.

A typical use case for this constraint is the inversion of whitelists to a blacklist. For example, if a user should not be able to see entries of a specific content type, you can deny access to those content types or allow access to all but entries of that content type:

{"and": [
  { "equals": [{ "doc": "sys.type" }, "Entry"] },
  { "not": { "equals": [{ "doc": "" }, "2PqfXUJwE8qSYKuM0U6w8M"] } }


This constraint evaluates if one condition returns true. The value is an array of constraints.

Use the constraint to enable an action for different resources. E.g. a user should only be allowed to read entries of a specific content type or all assets:

{"or": [
  {"and": [
      { "equals": [{ "doc": "sys.type" }, "Entry"] },
      { "not": { "equals": [{ "doc": "" }, "2PqfXUJwE8qSYKuM0U6w8M"] } }
  { "equals": [{ "doc": "sys.type" }, "Asset"] }

Roles collection

Get all roles

This endpoint returns a paginated list of roles for a given space. Each role contains a name, a description, permissions and policies, which describe what a user can and cannot do.

Create a role

Use this endpoint to create a custom role. The role name must be unique within the space.


Get a single role

Use this endpoint to read an existing single role.

Update a single role

Use this endpoint to update an existing role. You cannot use the endpoint to create a new role with a specific id.

Delete a single role

Use this endpoint to delete an existing role. You can only delete roles if there is no user in the space with only that role assigned, i.e. a user must have at least one role.


Snapshots represent an entity at a given time in the past. A snapshot is automatically created each time an entry or a content type is published.

Each snapshot has two top level objects, sys and snapshot. The snapshot object contains the content of the entity at the moment the snapshot was taken. The sys object contains meta information about the snapshot and has the following nested properties:

Field Type Description
type String Type of the resource. For snapshots it will always be Snapshot
createdAt Date Timestamp with the moment when the snapshot was created
createdBy Link A reference to the user who created the snapshot
id String The unique identifier for this snapshot
snapshotType String The type of snapshot. For now the only valid value is publish
snapshotEntityType String Type of the entity in the snapshot. Entry or ContentType

Entry Snapshots collection

Get all snapshots of an entry

Entry Snapshot

Get a snapshot of an entry

Content Type Snapshots collection

Get all snapshots of a content type

Content Type Snapshot

Get a snapshot of a content type

Space memberships

Space memberships collection

Get all space memberships

This endpoint returns a paginated list of all space memberships.

Create a space membership

Use this endpoint to create a space membership (or invite a user to a space). A user can and must be flagged as 'admin' or assigned to certain roles.

Space membership

Get a single space membership

This endpoint returns details about an existing space membership.

Update a single space membership

This endpoint allows you to change a space membership. Use this to assign additional roles or flag a user as 'admin'.

Delete a single space membership

This endpoint allows you to delete a space membership. It only changes if a user can access a space, and not the user record.

Note: It's possible to remove every administrator from a space which could mean there is no one left to manage the users. You can fix this by inviting a new user through the web app organization settings.

API keys

This endpoint allows you to manage Content Delivery API (CDA) keys. These tokens provide read-only access to a single space. You need to obtain a new token for every new space you want to access.

We recommend using different access tokens for different applications or delivery channels. For example, use one for an iOS app and another for an Android app. This allows you to revoke them individually in the future and manage your delivery channels independently.

API keys collection

Get all API keys

Create an API key

Personal access tokens

This set of endpoints allows you to manage personal access tokens. These tokens provide you with access to the Content Management API (CMA) and are an alternative means of authentication to our existing OAuth 2.0 flow.

A personal access token inherits the same access rights as your Contentful account. In other words, if you have access to multiple spaces and organizations, your token will too.

Personal access tokens collection

Create a personal access token

This endpoint allows you to create a personal access token. When creating, you'll need to specify at least one scope, which is used to limit a tokens access. The following scopes are supported:

  • content_management_read - Read-only access

  • content_management_manage - Read and write access

Since content_management_manage allows you to read and write, specifying

"scopes": ["content_management_manage"] is equivalent to:

"scopes": ["content_management_read", "content_management_manage"]

Note: This is the only time you will be displayed the token attribute, which contains your access token for the Content Management API. Please ensure you copy it and keep it in a safe place (e.g. outside of your source code repository, an environment variable on your server, ...)

Get all personal access tokens

This endpoint will return all active personal access tokens. Revoked tokens will not be returned with this collection.

Personal access token

Get a single personal access token

This endpoint returns details about an existing personal access token.

Token revoking

Revoke a personal access token

This endpoint allows you to revoke a personal access token. It will set revokedAt to the timestamp of when the request was received.

Note: This action can not be undone.



Get the authenticated user

This endpoint returns details about your Contentful user account.