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.

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:

• Between 1 and 64 characters.

• Consist of alphanumeric characters, minus -, underscore _ and a period ..

Represented as a regular expression, this is /^[a-zA-Z0-9-_.]{1,64}$/.

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.

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

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.

Examples:

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).

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

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:

{
  "sys": {
    "type": "Space",
    "id": "yadj1kx9rmg0"
  }
}

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.

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.

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.

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.

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.

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:

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

The Upload API, available at upload.contentful.com, 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 sys.id 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 sys.id 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.

Resumability

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"
        }
    }
}

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.

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.

Headers

Every webhook request includes the following predefined headers:

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 Content-Type header has the application/vnd.contentful.management.v1+json 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
X-Notify:subscribers
Authentication: subscribers

Body

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 fields.name 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.

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.

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.

and

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": "sys.contentType.sys.id" }, "2PqfXUJwE8qSYKuM0U6w8M"] }
]}

equals

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.

not

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": "sys.contentType.sys.id" }, "2PqfXUJwE8qSYKuM0U6w8M"] } }
]}

or

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": "sys.contentType.sys.id" }, "2PqfXUJwE8qSYKuM0U6w8M"] } }
  ]},
  { "equals": [{ "doc": "sys.type" }, "Asset"] }
]}

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:

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.

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.