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:

• 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}$/.

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

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: Once created, none of the sys properties can be changed. During creation of an entity, the value of sys.id is either automatically generated or specified in the URL (e.g. entries/entryId) of the initial PUT request. The only entity which always uses generated sys.id values is spaces.

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

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.

Environments allow you to develop and test changes to data in isolation from other environments. You can use them for all purposes in your development process like QA, staging environments or in continuous integration.

Environments are resources in a space and can be accessed by a unique identifier. This means that two spaces can have an environment with the same name.

A space can have multiple environments. A space has a minimum of one environment, which is called master. The master environment cannot be changed, deleted or renamed.

For a best practise explanation on how to use environments in your development workflow, please read the Managing multiple environments article in our knowledgebase.

Creating environments

To create other environments next to master, you need to have the default space admin role or a role, which allows you to manage and use all sandbox environments in this space. While creating an environment, you need to understand that it can only be a copy of the current state of the master environment. See the Environment aware Resources chapter below for more information on what resources are copied to an environment. It is not possible to create or have empty environments or environments based on older versions of a master environment.

To create an environment, make a request to PUT /spaces/<id>/environments/staging specifying the name in the payload like {"name": "My staging environment"}. After this request got a successful response, please query the single endpoint of that environment to check if the environment is already available.

You can also create an environment with any other environment as a source by providing the X-Contentful-Source-Environment header and providing it with the environment ID for the desired source environment.

Access content in an environment

To request content from an environment, you need to provide another fragment in the url. For example to get all entries from the previously created staging environment, use /spaces/<id>/environments/staging/entries.

Requests to /spaces/<id>/entries without the environment fragment will implicitly request content from the master environment.

Environment aware resources

The following resources are environment aware. This means upon creation of an environment, the following resources are copied from the master environment to the environment you want to create:

• Content Types

• Entries

• Assets

• Locales

• Extensions

• Editor Interfaces

Upon copying, all resources maintain their original metadata like sys.id or createdAt.

All other resources are available on a space level only. Personal access tokens allow access according to your role. This means if you have access to a space and have the default space admin role or a role, which allows to manage and use all sandbox environments in this space, you can use your PAT to access all environments. For CDA/CPA API key pairs, you can select the environments for which they have access, please refer to the API keys section in this document for more information.

Environment states

An environment can have different states determined by the sys.state property.

The master environment is always in state ready.

Environments and rate limiting

All requests to environments in a space count against the organizations rate limits bucket.

Environments and webhooks

Webhooks can be triggered for one or multiple environments by using the filters property of a webhook. Supported scenarios are:

• trigger only for specific environments by specifying environment constraints in the filters property (e.g. {"filters": [{"equals": [{"doc": "sys.environment.sys.id"}, "some-env-id"]}]})

• trigger for all environments by not setting any environment filters (e.g. {"filters": []})

• trigger only for the master environment by omitting the filters property or setting its value to null. This scenario handles webhooks created prior to introduction of environments in a backwards compatible manner.

Please refer the webhooks reference for more details.

There are no events for creating or deleting an environment.

Environments and snapshots

Snapshots are only available for entries and content types belonging to the master environment.

An environment alias allows you to access and modify the data of an environment, called the target environment, through a different static identifier.

You must opt-in to this feature in the Contentful web app on the Settings > Environments page. During this opt-in process, we create a default alias with the ID master. This alias cannot be renamed or deleted. Once you've opted in, you can create up to two more aliases. Only space admins can opt-in and manage environment aliases.

Aliases and target environments can be used to enhance your development and deployment workflows. For example, you can safely apply content model changes and roll them back when necessary or use them in your CI/CD pipelines.

Check out the concepts section to find out more about environment aliases.

Creating environment aliases

When you set up this feature for your space, we create a default master environment alias for you. You can also create up to two more aliases by sending a PUT request to spaces/<id>/environment_aliases/<alias_id> and specifying the target environment in the payload as described below.

Aliases must always target an existing environment. Environments targeted by aliases cannot be deleted. The master environment alias cannot be deleted.

Updating environment aliases

To change the target environment of an environment alias, you need to be a space admin. Similar to environments, you cannot change an environment alias id.

You do this by sending a PUT request to /spaces/<id>/environment_aliases/<alias_id> specifying the target environment in the payload as described below.

Deleting environment aliases

You can delete an environment alias by sending a DELETE request to /spaces/<id>/environment_aliases/<alias_id>. It is not possible to delete the master alias or its target environment.

Accessing data using an environment alias

To request data using the environment alias, specify the alias ID instead of the ID of the target environment.

For example, if the master alias targets an environment with ID target-environment, you can access its data from /spaces/<id>/environments/master/....

Master alias

Requests without the environment alias fragment will be treated like requests to the master environment alias. For example, requests to /spaces/<id>/entries will have the same outcome as requests to /spaces/<id>/environments/master/entries.

New environment properties when using aliases

Fetching an environment can now be done through the environment's ID or alias ID.

New properties are introduced on environments that are targeted by aliases.

• Fetching the environment using the environment identifier e.g. target-environment

GET /spaces/{space_id}/environments/{environment_id}

#  Sample response body
{
  "name": "target-environment",
  "sys": {
    "type": "Environment",
    "id": "target-environment",
    "version": 1,
    "space": { ... },
    },
    # NEW - list of environment aliases that target this environment
    "aliases": [{
      "sys": {
        "type": "Link",
        "linkType": "EnvironmentAlias",
        "id": "master"
      }
    }],

    "status": { ... },
    "createdBy": { ... },
    "createdAt": "2018-10-08T09:07:03Z",
    "updatedBy": { ... },
    "updatedAt": "2018-10-08T09:07:03Z"
  }
}

• Fetching the environment using the environment alias identifier master

GET /spaces/{space_id}/environments/{environment_alias_id}

# Sample response body
{
  "name": "master",
  "sys": {
    "type": "Environment",
    "id": "master",
    "version": 1,
    "space": { ... },
    # NEW - the targeted environment
    "aliasedEnvironment": {
      "sys": {
        "type": "Link",
        "linkType": "Environment",
        "id": "target-environment"
      }
    },
    # NEW - list of environment aliases that target this environment
    # for consistency we also return the aliases
    "aliases": [{
      "sys": {
        "type": "Link",
        "linkType": "EnvironmentAlias",
        "id": "master"
      }
    }],

    "status": { ... },
    "createdBy": { ... },
    "createdAt": "2018-10-08T09:07:03Z",
    "updatedBy": { ... },
    "updatedAt": "2018-10-08T09:07:03Z"
  }
}

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 an entry in the Contentful Web App.

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.

To get started with UI extensions please refer to our dedicated extensibility section.

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

• {type: "Integer"}

• {type: "Number"}

• {type: "Date"}

• {type: "Boolean"}

• {type: "Location"}

• {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.

Content tags allow you to group entries and assets within your space environment. This makes it much easier to find and organize content.

Tags are environment-scoped (meaning, they exist within and are unique to an environment). They are only available via the Content Management API.

To learn about using tags in the web app, see our content tags article in our Help Center.

A tag includes the following properties:

• name: A human-readable unique identifier for the tag

• id: A unique identifier for referencing the tag

Note: Currently, only space admins and users with permission to manage tags can create and manage tags.

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. There are however some differences:

• The CMA does not support the include and locale parameters.

With the introduction of content tags, you can query for entries / assets by their content tags via the CMA.

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.

Custom headers

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

Custom headers are provided with the headers property of the Webhook Definition:

{
  ...,
  "headers": [
    { "key": "X-Notify", "value": "subscribers" },
    { "key": "Authentication", "value": "subscribers" }
  ]
}

You can mark a header as secret. Value of secret headers is hidden in the Web App, API responses and logs. The first time you define a secret header you need to provide its value and the secret flag set to true:

{
  ...,
  "headers": [
    { "key": "X-Notify", "value": "subscribers" },
    { "key": "Authentication", "value": "subscribers", "secret": true }
  ]
}

Any consecutive update can omit the value property as long as the secret is true. Previously provided value will be used in this scenario:

{
  ...,
  "headers": [
    { "key": "X-Notify", "value": "updated subscribers" },
    { "key": "Authentication", "secret": true }
  ]
}

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.

Filtering webhook calls

In many use cases receiving a webhook call for all the events taking place in Contentful leads to complex filtering logic that has to be implemented on the receiving side. There are two mechanisms allowing webhook calls to be triggered conditionally:

• selection of a triggering event(s)

• filtering based on properties of a webhook payload

An event is a combination of the entity type and an action performed on it. For example the Entry.save event happens when an entry is updated with the CMA. ContentManagement.Entry.save is the topic for this event.

To select which events should trigger a webhook call set the topics property of a webhook to one or more event names. You can use a wildcard character * to indicate all entity types or actions should cause a webhook call. Please note that if you use the wildcard character and we add new entity types or actions your webhook receiver will be called with new events.

Possible values for topics are:

• ["*.*"] will trigger a webhook call for all the supported events in Contentful

• ["Entry.*"] will trigger a webhook call for all actions performed on entries

• ["*.save"] will trigger a webhook call when any of supported entities is saved

• ["Entry.save", "Entry.delete"] will trigger a webhook call only for the events listed

Once triggering events are selected webhook calls can be narrowed down further using webhook payload filtering.

There are 3 webhook payload properties you can filter on:

• sys.id - entity ID

• sys.environment.sys.id - environment ID

• sys.contentType.sys.id - content type ID (applicable only to entries)

These properties can be used as doc in the filters. There are 6 filters available:

{"equals": [
  {"doc": "sys.id"},
  "main_nav"
]}

{"not": {"equals": [
  {"doc": "sys.id"},
  "main_nav"
]}}

{"in": [
  {"doc": "sys.environment.sys.id"},
  ["qa", "staging"]
]}

{"not": {"in": [
  {"doc": "sys.environment.sys.id"},
  ["qa", "staging"]
]}}

{"regexp": [
  {"doc": "sys.environment.sys.id"},
  {"pattern": "^ci-.+$"}
]}

{"not": {"regexp": [
  {"doc": "sys.environment.sys.id"},
  {"pattern": "^ci-.+$"}
]}}

The filters property of a webhook holds zero or more filters in an array. While deciding if a webhook should be called all filters are joined with logical AND.

If there is no value for the filters property (or it is null) then by default a webhook will be triggered only in the master environment.

Combining all the mechanisms together we can achieve fine-grained webhook calls. The following webhook will be triggered only for (un)publish actions performed on entries with IDs main_nav or footer_nav in all environments prefixed with test-:

{
  "name": "My webhook",
  "url": "https://my-webhook-receiver.com/ping",
  "topics": [
    "Entry.publish",
    "Entry.unpublish"
  ],
  "filters": [
    {"in": [{"doc": "sys.id"}, ["main_nav", "footer_nav"]]},
    {"regexp": [{"doc": "sys.environment.sys.id"}, {"pattern": "^test-.+$"}]}
  ]
}

Transforming webhook calls

By default every webhook call:

• uses the POST HTTP method

• has the Content-Type header set to application/vnd.contentful.management.v1+json

• does not have the Content-Length header set

• sends a predefined body depending on the triggering event (as described above)

If you control the code of your webhook receiver you can respond to the default webhook call appropriately by implementing a custom logic in your receiver. The situation is different if you try to call an API you don't control with a webhook: most likely the default webhook payload won't adhere to the format expected by the API.

The transformation property of a webhook definition allows you to define:

• custom HTTP method

• custom Content-Type header

• if automatically computed Content-Length header should be included

• custom webhook call body that may or may not make use of the default webhook body

The transformation property is an optional object containing the following properties. None of these properties is required.

transformation.method can be one of:

• POST (default)

• GET

• PUT

• PATCH

• DELETE

transformation.contentType can be one of:

• application/vnd.contentful.management.v1+json (default)

• application/vnd.contentful.management.v1+json; charset=utf-8

• application/json

• application/json; charset=utf-8

• application/x-www-form-urlencoded

• application/x-www-form-urlencoded; charset=utf-8

Using the last two options will convert the JSON body to URL encoded form data.

transformation.includeContentLength can be either true or false. If true the Content-Length header will be present with its value set to automatically computed byte length of the request body.

transformation.body can be any arbitrary JSON data structure. It will be used as the webhook call body. It's possible to use values from the original webhook payload in the transformed body. There are two ways to resolve original values:

Resolving a whole value

1. In your data structure introduce a string value that starts with { and ends with } in a place you want to resolve the original value

2. In between curly braces put an absolute JSON pointer to the property you want to resolve; the original webhook body is stored in the payload top-level namespace

3. The string value containing a pointer will be replaced with the resolved value

For example, given the following original payload:

{
  "sys" {
    "id": "entry-id"
    "type": "Entry"
  },
  "fields": {
    "title": {
      "en-US": "hello world"
    }
  }
}

And the following body transformation:

{
  "entryId": "{ /payload/sys/id }",
  "title": "{ /payload/fields/title }"
}

Your webhook will be called with:

{
  "entryId": "entry-id",
  "title": {
    "en-US": "hello world"
  }
}

Using string templates

1. In your data structure introduce a string value that contains an absolute JSON pointer to the property you want to resolve, wrapped with { and }

2. The original webhook body is stored in the payload top-level namespace

3. JSON pointers will be replaced with resolved values

4. All values, including complex ones, will be stringified

For example, given the following original payload:

{
  "sys" {
    "id": "entry-id"
    "type": "Entry"
  },
  "fields": {
    "title": {
      "en-US": "hello world"
    }
  }
}

And the following body transformation:

{
  "entityInfo": "Entity of type { /payload/sys/type } with ID { /payload/sys/id }",
  "title": "Entity title is { /payload/fields/title/en-US }",
  "stringified": "Let's try to stringify an object: { /payload/fields/title }"
}

Your webhook will be called with:

{
  "entityInfo": "Entity of type Entry with ID entry-id",
  "title": "Entity title is hello world",
  "stringified": "Let's try to stringify an object: {\"en-US\":\"hello world\"}"
}

Helpers

In some cases, there can be a need for trimming or slightly modifying certain fields before delivering them to the webhook target. Contentful provides numerous helpers that can be used at the transformation level. For example:

{
  "content": "{ first-paragraphs 2 /payload/fields/content/en-US }",
}

Above-mentioned example limits the content field with first 2 paragraphs. If the content field has more than two paragraphs, the rest of the text gets trimmed. In addition to trimming content, helpers are useful in modifying or refining content. Following is another transformation, using the strip-stop-words helper:

{
  "keywords": "{ strip-stop-words /payload/fields/content }",
}

The above transform filters out stop words and delivers only the keywords in the content field. For example:

Art is the expression or application of human creative skill and imagination

becomes:

art expression application human creative skill imagination

Refer the table below to see the full list of available functions:

URL transformation

Webhook URLs can contain JSON pointers as described in the previous section. They always follow string template resolution logic. For example a webhook defined as follows will result in a call to https://my-webhook-endpoint.com/my-entry-1 for an entity with ID my-entry-1.

{
  "name": "Dynamic URL",
  "url": "https://my-webhook-endpoint.com/{ /payload/sys/id }"
}

Transformation context

When transforming both request body and URL, JSON pointers are used to resolve values. Values are resolved from a context object. Currently the context object has three properties:

• payload contains the original webhook payload

• topic is a string containing the webhook topic

• user is a stripped-down version of a User entity for the user who executed action triggering the webhook call; the only available pointer is { /user/sys/id }

AWS Webhook Integration

AWS offers over 100 cloud services, with the most prominent examples being data stores (S3, DynamoDB), serverless engines (Lambda), queuing systems (SQS) and many more.

Most AWS services use AWS Signature Version 4 to authenticate requests to their APIs. Computing the signature requires a prepared canonical request (a request without the Authorization header) and AWS credentials. They are all used as the input for the AWS Signature Version 4 algorithm. Its output is a value that should be used as the Authorization header.

The headers and body values of a webhook are likely changing between individual requests. This means the canonical request will differ and previously computed Authorization headers will be invalid. The proxy that the AWS Webhook Integration is using will re-compute the signature for every request.

If you have AWS Webhook Integration enabled you can use its proxy within a webhook so all requests will be automatically signed. You can either start from a webhook template or follow these steps to configure it manually:

1. Create a webhook performing a canonical AWS request to the service you use. All standard features available for webhooks are available.

2. Replace amazonaws.com with awsproxy.contentful.com in the webhook URL.

3. Set a X-Contentful-AWS-Proxy-Key-Id header with your AWS Access Key ID.

4. Set a X-Contentful-AWS-Proxy-Secret header with your AWS Secret Access Key. Make sure it's marked as secret!

5. Optionally you can set a X-Contentful-AWS-Proxy-Content-Type header to a custom Content-Type value if a service being called requires it (for example application/x-amz-json-1.0).

The proxy will automatically sign all requests using the credentials provided. Credentials have to have IAM role assigned allowing to perform selected action.

The proxy is an internal system and cannot be accessed from the public Internet. Only our webhook system can use this proxy.

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.

The following permissions are supported:

and each of those permission can have the following values:

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.

Snapshots are only available for entries and content types belonging to the master environment.

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:

These endpoints allow you to manage Content Delivery API (CDA) and Content Preview API (CPA) keys. These tokens provide read-only access to one or more environments. For each environment you want to access with a given token, you need to include a link to this environment in the environments property when creating or updating. Only the environments specified in this property can be accessed using this token and any CDA or CPA request using this token to access content from an environment not specified here will result in a 404 error. If the environments key is not specified, the token will have access to the master environment by default.

We recommend using different access tokens for different environments in your development process. For example, use one for your production environment and another for staging or continuous integration. This allows you to revoke them individually in the future and manage your delivery channels independently.

Note: It may take some time for a new or updated API key to propagate through Contentful systems, typically within seconds. If you encounter HTTP 401 errors, for example when using an API key recently created during CI, you may need to add a delay or poll until the 401 status resolves.

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.

Tasks are the building blocks to setup editorial workflows on your content. They allow editorial teams to distribute work with clear accountability.

Unresolved tasks block entry publishing

The entry publishing method will return an error if an attempt is made to publish an entry which has unresolved tasks. This is a measure to avoid the accidental publication of content which is not ready to be released.

There can be cases where an entry has to be published even though it has unresolved tasks. There are two options in this case:

• a space admin resolves or removes the tasks and then publishes the entry

• the creators of the unresolved tasks remove them and then publish the entry

Availability

Tasks are only available on enterprise space types.

Task schema

A Task has four top level properties: assignedTo, body, status and sys. These are described in detail below.

In addition to the common sys properties tasks have the following extra sys properties

Actors

When talking about tasks in this documentation we consider the following actors:

• Task creator, the person who created the task.

• Task assigner, the person who assigns a task to an user. It will usually be the same as the creator.

• Task assignee, the person who has to do the work specified in the task and resolve once finished.

Enables users to create actions that will be performed on an entity at given time in the future.

Currently supported actions:

• Publish an entry

• Unpublish an entry

Find out more regarding entry publish in entry publish docs.

Availability

Scheduled action feature is globaly available for all customers except those on legacy pricing plans.

Notifications

If an entry fails to publish at the scheduled time due to entry validation errors, the user who scheduled the action is notified via email.

Limitations

The current limit of scheduled actions in scheduled status is 500. Once it's reached, no additional scheduled actions can be created.

In addition there is a limit of 200 entries that can be scheduled to be executed in a single minute.

Scheduled action schema

The scheduled action has five top level properties: entity, environment, scheduledFor and action. These are described in detail below.

Scheduled action status

Every scheduled action has a sys.status field. It contains one of the following values:

Once the scheduled action is created the status is set to scheduled. In case the scheduled action is canceled before the execution, the status is set to canceled.

Once the scheduled action was executed the status is set to succeeded in case of successful execution and to failed if any error happened during execution process.

AppDefinition is an entity type that stores all information about a single Contentful app on the organization level. By itself this entity does not do anything. To use an app you need to create an AppInstallation in a selected space-environment pointing to your definition.

Definitions centralize app management within an organization. Changes to a definition will automatically be propagated to all of its installations. There is no need to update installations when updating a definition.

App definition properties

• name: a human-readable name of the app

• src: publicly available source URL of the app; requires HTTPS with exception of localhost (for development)

• locations: list of places in the Web App where the app can be rendered; see below

• parameters: definitions of configuration parameters

App locations

Locations are described in more detail in the SDK reference.

The locations property is an array of one or more of:

{
 "location": "entry-field",
 "fieldTypes": [
  { "type": "Symbol" }
 ]
}

Entry field location

All valid fieldTypes are:

• Short text: { "type": "Symbol" }

• Short text, list: { "type": "Array", "items": { "type": "Symbol" } }

• Long text: { "type": "Text" }

• Rich text: { "type": "RichText" }

• Number, integer: { "type": "Integer"}

• Number, decimal: { "type": "Number" }

• Boolean: { "type": "Boolean" }

• Date and time: { "type": "Date" }

• Location: { "type": "Location" }

• JSON object: { "type": "Object" }

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

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

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

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

Page location

When you add a page location in your AppDefinition, there is the possibility to add an optional navigationItem property to it.

{
  "location": "page",
  "navigationItem": {
    "name": "My app",
    "path": "/my-app"
  }
}

{
  "location": "page",
  "navigationItem": {
    "name": "My app",
    "path": "/my-app"
  }
}

If provided, a link will be added to the "Apps" navigation item in the Contentful Web App pointing to your app installation.

Example

The following app definition is called "Hello world" which is served from https://example.com/hello-app.html and can be rendered both as an editing widget for short text fields and as an app configuration screen:

{
  "name": "Hello world",
  "src": "https://example.com/hello-app.html",
  "locations": [
    {
      "location": "entry-field",
      "fieldTypes": [
        { "type": "Symbol" }
      ]
    },
    {
      "location": "app-config"
    }
  ]
}

AppEventSubscription is an entity type that defines Contentful event topics (for example: "entry publication") to which an app is subscribed. Event subscriptions can be defined only for existing AppDefinitions. An app only receives events about content entities in a space-environment of its installation.

App definition properties:

• targetUrl: a URL to be called with events specified as topics; requires HTTPS

• topics: list of event topics

All listed properties are required.

All valid topics are:

• Entry.create

• Entry.delete

• Entry.save

• Entry.publish

• Entry.unpublish

• Entry.archive

• Entry.unarchive

• Asset.create

• Asset.delete

• Asset.save

• Asset.publish

• Asset.unpublish

• Asset.archive

• Asset.unarchive

• ContentType.create

• ContentType.delete

• ContentType.save

• ContentType.publish

• ContentType.unpublish

AppKey is an entity that represents a key pair that can be used by an app to make a signed request to Contentful in order to issue an access token for a specific app installation.

The top-level jwk property holds a standard JSON Web Key. The following properties require constant values:

• alg: "RS256"

• kty: "RSA"

• use: "sig"

As shown, the generated key must be a RSA key using the RS256 algorithm. To generate such a key pair, openssl (you may need to download a binary if you're not on Mac or Linux) can be used:

openssl req -x509 -newkey rsa:4096 -nodes -batch -noout -keyout key.pem
openssl rsa -in key.pem -pubout -outform DER -out key.der.pub

The content of key.der.pub can be used as the first element of the x5c array. Please note:

• the string needs to be encoded as a base64 string

• Contentful never expects your private keys: make sure you're uploading the public key!

The signature value is used as both kid and x5t. We will also use it as a globally unique key identifier within Contentful. To generate a signature use:

openssl dgst -binary -sha256 < key.der.pub | openssl base64 | sed 's/+/-/g; s/\//_/g; s/=*$//'

Limitations:

• the same key pair cannot be used for more than one app

• the limit of keys per app is 3 (which makes it possible to perform a rotation while keeping one backup key operational)

If you do not want to create your own key pair with openssl, we also offer the functionality to generate the key pair for you. It is important to note that we do not store any private keys on our side and only store the public key. We show the private key only once in the response of the POST request, so make sure that you store the private key and keep it safe. Once the response is lost, there is no other way to retrieve the private key.

AppInstallation is an entity type that indicates if an app described by some AppDefinition is installed in a space-environment.

An app installation can store app-specific configuration variables in its parameters property. This property is optional, and when present it can be a free-form object with values managed by the code of the app with the SDK. The only limitation is that the stringified value of parameters cannot be longer than 16kB.

App installations are copied in the process of environment creation. This means that when app X is installed in the master environment and then you create a staging environment out of it, both the installation and its parameter will be copied to the target (staging) environment.

AppAccessToken entities allow apps to act on their own in space-environments in which they are installed.

In terms of access, an access token for an app:

• is scoped to a specific space-environment matching the space-environment of an app installation

• allows all actions on the following entity types: ContentType, EditorInterface, Entry, Asset

• allows reading of the app's configuration parameters

To obtain an access token, an app needs to use one of its active private keys (with a corresponding public key registered as an AppKey) to sign a JWT.

The following claims are mandatory:

• iss: Issuer - sys.id value of the AppDefinition

• exp: Expiry - number of seconds the JWT should be valid; not longer than 10 minutes

The following header properties are mandatory:

• typ: "JWT"

• alg: "RS256"

A JWT created this way can be used to call the endpoint described below. The response will contain the value of the app access token as the token property. The token can be used to call CMA endpoints (as outlined above) for 10 minutes. The token can be cached until it expires.

Enables users to query organization API usage data. You can further filter by Contentful API types (cma, cda, cpa, gql) through the parameter metric. Results are paginated and support ordering.

Permissions

Usage API is available to Enterprise, Team and Community tiers. Enterprise and Team customers can access historical usage data with API batch size of 45 days. Community tiers can access the last 45 days of historical usage data. Usage API calls can only be made by a user with the Organization Admin or Organization Owner role.