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

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 client libraries). 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 includes a sys property. The sys object contains system managed and resource dependent information. At minimum sys defines the sys.type property.

During entity creation, the value of sys.id is either automatically generated or can be specified in the URL (e.g. /environments/master/entries/my-custom-id) of the initial PUT request. The only entity which always uses generated sys.id values is spaces.

Note: sys metadata fields can not be changed programmatically.

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

Date and time must be formatted according to ISO 8601.

The table below displays the supported date and time formatting:

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.

When cloning environments, please note that it is a heavy duty process that takes time proportionate to the amount of data contained in the source environment.

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

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:

• App Installations

• Assets

• Content Types

• Editor Interfaces

• Entries

• Extensions

• Locales

• Releases

• Scheduled Actions

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. Snapshots are not available in the sandbox environments.

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 modeling your content.

UI Config describes views and folders in the Contentful web app. A view is a list of filters and sorting behavior that refines the content list according to different criteria.

You can set UI Config for all members in an environment, or just for the current user.

Templates allow you to create, compose and replicate configurations of content models across your multi-space set-ups. You can build templates from your existing content models and install them in other spaces and environments.

To support installations of content model templates across multiple spaces, the EnvironmentTemplateInstallation domain type has been implemented. The EnvironmentTemplateInstallation entity represents the installation of one template in a specific environment. In their current form, templates can only be used to distribute content types and editor interfaces.

Templates are managed at organizational level.

Cross-space references (formerly known as References across spaces) allow you to link content across multiple spaces. Using cross-space references, you can create reusable content and update multiple spaces with the same piece of content. To accommodate referencing across multiple spaces, the ResourceLink field type has been added. The ResourceLink field carries references to entities in separate spaces. All ResourceLink fields are configured in the ContentType definitions as usual fields and accept the allowedResources validation rule. This validation restricts the entities that can be linked by the field.

Supported field properties: localized, required, omitted and disabled.

Contentful Resource Names

With cross-space references, the Contentful Resource Name (crn) API identifier is used.

A crn is a formatted string used to describe an object in the API domain. It uses a shared syntax that can be resolved across Contentful services. Currently, crn is only used in the context of cross-space references to recognize a Contentful space, environment, or entry.

The respective syntax templates are:

crn:contentful:::content:spaces/<:spaceId> crn:contentful:::content:spaces/<:spaceId>/environments/<:environmentId> crn:contentful:::content:spaces/<:spaceId>/entries/<:entryId> crn:contentful:::content:spaces/<:spaceId>/environments/<:environmentId>/entries/<:entryId>

The <:spaceId>, <:environmentId>, and <:entryId> portions must contain standard resource IDs. In the following snippets, the "{crn}" placeholder will be used where one of these is needed.

Note: Omitting the environment in a crn is equivalent to referencing the master environment.

Similar to cross-space references that allow you to link content across multiple spaces, Native external references allow you to integrate content from external sources using the Contentful App Framework.

To model the data from third-party systems, the following entity types have been introduced:

• Resource Provider - a third-party system that provides resources. Each provider can have multiple resource types.

• Resource Type - a specific type of resource (not the resource itself) that is provided by a resource provider.

• Resource - a representation of real data in an external system.

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.

Entry object description

Entry object consists of the following top-level properties:

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

Asset keys are used when signing Embargoed Asset URLs. This feature is only enabled on specific plans. Reach out to your Sales representative for more information about feature availability.

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

Tags are assigned to entries and assets to group them in your environment. Tags help you to easily search and organize content.

Tags are environment-scoped which means that they exist within and are unique to an environment. All tags are available via the Content Management API.

To learn how to use tags in the web app, please refer to our Tags category 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

• visibility: A sys property with value of public or private that determines if a tag is publicly accessible or not

Note: Only space admins and users with permission to manage tags can create and manage tags.

Tag visibility

There are two visibility options for Tags:

• private: Tags with this visibility option are only available via the Content Management API to all users with relevant permissions within the space. This is the default visibility.

• public: Tags with this visibility option are available via all our APIs (CDA, CMA and CPA).

{
    "name": "Tag Name",
    "sys": {
        "visibility": "public | private", // The new visibility property
        "id": "TagID",
        ... // Other sys properties
    }
}

Note: The tag visibility cannot be changed after the tag is created.

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 tags, you can query for entries / assets by their 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.

Contextual Event Headers

Additionally, extra headers may be emitted to provide context for an action, such as an entry being published by a scheduled action or as part of a release.

Consuming services can use these headers to correlate events across multiple webhook calls to group the calls into a single downstream action, such as debouncing a rebuild of a website

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

Header values may contain values from the original payload: see header transformation.

Signed Request Verification Headers

When you've configured a webhook signing secret in the webhook settings of your space, a signature will be generated for all webhook requests coming from events in that space. When a consuming service receives a request, it can compute a signature in the same way. If the secret is the same, the signatures will match too, thus verifying that the sender knows the secret. For this reason, it is also important to not share the secret with any third party.

This signature and some additional metadata is then added to the headers of the request before it is sent. The headers look like this:

Consuming services can use these headers to verify the authenticity and integrity of incoming webhooks. See verifyRequest in node-apps-toolkit for more information.

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 and retry policy

Contentful uses 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 429 or >= 500, the webhook periodically retries its request.

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 6 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 Entry events)

• sys.createdBy.sys.id - User ID, created by (not applicable to Unpublish and Delete events)

• sys.updated.sys.id - User ID, updated by (not applicable to Unpublish and Delete events)

• sys.deletedBy.sys.id - User ID, deleted by (only applicable to Unpublish and Delete events)

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. This can be achieved by JSON pointers in the body JSON. Depending on the referenced data either whole values or strings are resolved.

URL transformation

Webhook URLs can contain JSON pointers that are resolved to values from the original payload. The value resolution always follow the 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 }"
}

Header transformation

Custom header values can contain JSON pointers as described below. This is achieved by JSON pointers that are resolved using the string template resolution logic.

The following header definition

{
  ...,
  "headers": [
    { "key": "X-CTFL-Entity-ID", "value": "{ /payload/sys/id }" },
    { "key": "X-CTFL-Entity-Type", "value": "{ /payload/sys/type }" }
  ]
}

will result in two headers on the actual webhook call if the webhook was triggered by a change of entry 42:

X-CTFL-Entity-ID: 42
X-CTFL-Entity-Type: Entry

Secret and HTTP Basic Auth headers are not transformed. Also, the header keys are not transformed.

Resolution strategies

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:

Transformation context

When transforming request body, URL, and headers, 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.

WebhookSigningSecret is an entity that represents a symmetric key shared between Contentful and a webhook receiver. Contentful uses this secret to sign requests sent to a webhook receiver, which allows a webhook receiver to verify that requests it receives are made by legitimate users of the app through Contentful. WebhookSigningSecrets are a Space-level resource and only one can be created per Space.

Storing a WebhookSigningSecret for a webhook in Contentful enables:

1. All future webhook calls requests will be automatically signed using the secret. The receiving backend can decide whether it wants to validate this signature or not, so enabling this should not have any immediate effect until used.

There are two constraints on the secret:

1. It must be exactly 64 characters long.

2. It must match this regular expression: /^[0-9a-zA-Z+/=_-]+$/. This also means secrets using the hex or base64 character set are allowed.

We recommend using a cryptographic pseudorandom number generator to generate a secret. See our guide on request verification for examples on how to generate a secret.

Creating custom roles allows an administrator to restrict the access of users to certain resources. Roles follow an "allow list" 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).

For information on how policies are specified, refer to the programmatic role management guide.

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 not available in the sandbox environments (not master environment). While this is true for sandbox environments, aliasing can effect how snapshots are created. For example, having a 'master' alias pointing to a sandbox environment will create snapshots for that environment which might conflict when entries with the same ID exist.

Each snapshot has two top level objects: sys and snapshot.

The sys object contains technical information about the snapshot and has the following nested properties:

The snapshot object contains the content of the entity at the moment the snapshot was taken (excluding the Entry.metadata field).

Note that snapshot object has two fields only, similar to the three-field structure of Entry:

• snapshot.fields - holds the fields of the Entry at the time of the snapshot

• snapshot.sys - holds the technical details of the Entry at the time of the snapshot

There is no snapshot.metadata field because when taking a snapshot of the Entry, the metadata field (usually containing user-defined tags) is not stored in the snapshot.

Collection filters

When querying large snapshots or large collections, the size in bytes of the resulting dataset may be quite large. To avoid downloading large datasets with unnecessary data from the API, use the select operator.

With the select operator, you can instruct the API to only return specific fields from your dataset.

For example, to limit the returned dataset to fields representing snapshot id and snapshot creation time, use the select operator in the form of: select with the value of sys.id,sys.createdAt.

Note that using the select operator to query the Snapshots API is more flexible and permissive than the more restrictive behavior of querying the Content Delivery API with select. When using the select operator with the Snapshots API you can:

• request properties with depths larger than 2. For example, select with value sys.id,snapshot.fields.title,snapshot.fields.description.

• request a field with given locale and specify it at the end of the property path. For example, select with value sys.id,snapshot.fields.description.es,snapshot.fields.description.en.

• query snapshots of a specific Entry without having to specify the content-type argument.

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.

This set of endpoints allows you to manage CMA tokens (Personal access tokens, CLI tokens, OAuth application 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 CMA 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.

Users can add comments to an entry. This allows for teams to collaborate and have conversations.

Availability

Comments are globally available for all customers.

Mentions in comments

Mentions in comments allow you to tag collaborators in the comments tab of an entry. By including the “@” followed by an individual's or team's name, you can directly engage in conversations regarding feedback, workflow statuses, or general comments.

Only when creating a comment that includes a mention of a collaborator, the mentioned recipient will receive an email notification. The following comments that do not include a mention of a user or team, such as replies or updates, will not be subject to notifications.

To mention users, you must provide a body in Contenful's rich-text format. There, include a node of type mention where you indicate the user ID, using the following code:

{
        "nodeType": "document",
        "data": {},
        "content": [
          {
            "nodeType": "paragraph",
            "data": {},
            "content": [
              {
                "nodeType": "text",
                "value": "Text ab with ",
                "marks": [],
                "data": {}
              },
              {
                "nodeType": "mention", // new node type
                "data": {
                  "target": {
                    "sys": {
                      "id": "userId",
                      "type": "Link",
                      "linkType": "User"
                    }
                  }
                },
                "content": []
              },
            ]
          }
        ]
      }

To mention teams, instead of indicating the 'user ID' and a 'linkType: User', include the 'team ID' and use 'Team' as the 'linkType'. For example:

{
        "nodeType": "document",
        "data": {},
        "content": [
          {
            "nodeType": "paragraph",
            "data": {},
            "content": [
              {
                "nodeType": "text",
                "value": "Text ab with ",
                "marks": [],
                "data": {}
              },
              {
                "nodeType": "mention", // new node type
                "data": {
                  "target": {
                    "sys": {
                      "id": "teamId",
                      "type": "Link",
                      "linkType": "Team"
                    }
                  }
                },
                "content": []
              },
            ]
          }
        ]
      }

To submit comments with rich-text, provide the following header: x-contentful-comment-body-format to mention a user in the comment with the value: rich-text. You can request a comment using either format plain-text or rich-text by passing either value in this header.

The request for the header will return the following:

{
  "sys": {
    "version": 0,
    "parent": {
      "sys": {
        "id": "string",
        "linkType": "Comment",
        "type": "Link"
      }
    },
    "updatedAt": "string",
    "updatedBy": {
      "sys": {
        "id": "string",
        "linkType": "User",
        "type": "Link"
      }
    },
    "createdAt": "string",
    "createdBy": {
      "sys": {
        "id": "string",
        "linkType": "User",
        "type": "Link"
      }
    },
    "parentEntity": {
      "sys": {
        "id": "string",
        "linkType": "Entry",
        "type": "Link"
      }
    },
    "environment": {
      "sys": {
        "id": "string",
        "linkType": "Environment",
        "type": "Link"
      }
    },
    "space": {
      "sys": {
        "id": "string",
        "linkType": "Space",
        "type": "Link"
      }
    },
    "type": "Comment",
    "id": "string"
  },
  "body": Object
}

If you request a comment that was previously created as rich-text and request without a header or plain-text header specification, the comment will be returned in plain-text. In the plain-text representations, mentions will have the following format: User(id=1xGZIRXr2WPnsLkKfREo0z)``. You can also fetch the rich-textrepresentation of aplain-textcomment by passingrich-text` as the value in the above header.

Comment schema

A comment has two top level properties: body and sys. These are described in detail below.

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

The property resolvedBy is only defined if the comment is resolved. Reopening a comment will remove the field from the sys property.

Users can add comments to a workflow. This allows for teams to provide additional context to a certain workflow step change.

Availability

Workflow comments are globally available for all customers.

Workflow comment schema

A worklfow comment has two top level properties: body and sys. These are described in detail below.

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

The property resolvedBy is only defined if the comment is resolved. Reopening a comment will remove the field from the sys section.

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 all Premium plans and spaces (in former Enterprise plans Tasks are only available on Performance 1x and above space types).

Task schema

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

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

Both properties resolvedAt and resolvedBy are only defined if the task is resolved. Reopening a task will remove both fields from the sys section.

Actors

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

• Task creator, the person or app that created the task.

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

• Task assignee, the person or team that has to do the work specified in the task and resolve once finished. If a team is assigned, team members can act on its behalf (e.g. resolve a task).

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

Currently supported entities and actions:

• Entry: publish and unpublish

• Asset: publish and unpublish

• Release: publish and unpublish

Find out more regarding entry publish in entry publish docs.

Availability

Scheduled action feature is globally available for all customers.

Notifications

If an entry fails to publish at the scheduled time due to validation errors, an email will be sent to the user that created the Scheduled Action informing that it failed.

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 scheduled actions that can be executed in a single minute.

The scheduled date for a scheduled action when creating or updating must be between the current time and up to 5 years in the future.

There is a limit of 200 entities when publishing an entity with references, e.g. a Compose page. The scheduled action will fail if the number of entities exceeds that limit.

Scheduled action schema

The scheduled action has the following properties:

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.

Scheduled action payload

Payload is used to provide additional information about how the scheduled action will be executed. It supports the following properties:

Enables users to create releases that contains entries or assets and perfom actions on them.

Currently supported actions:

• Create release

• Update release

• Delete release

• Fetch release

• Query relases

• Publish release

• Unpublish release

• Validate release

Availability

Releases feature is globally available for all customers. In the Contentful web app this feature is available for the customers that purchased Launch application.

Limitations

Release cannot contain more then 200 entities or assets in total.

Release schema

The release entity has following schema:

Enables users to create actions that will perform asynchronously on a batch of entities on the environment level.

Entity types that are currently supported:

• Asset

• Entry

Currently supported actions:

Availability

Bulk actions are globally available for all customers.

Notifications

Since the execution of batch actions occur asynchronously, the status of the action can be checked by retrieving the batch action by the id in the response.

Limitations

Currently there are following limitations regarding bulk actions feature:

• Max active bulk actions per space is limited to 5.

• Max of 200 items per bulk action.

Bulk action schema

The bulk action has 4 top level properties as described below:

System property indicating the status of the bulk action is located inside the root sys property.

The status of the bulk action could be one of following:

• created: bulk action is created, but not acted on

• inProgress: the action has been started

• succeeded: the action has successfully completed

• failed: the action execution failed

AppDefinition is an entity type that stores all information about a single 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.

A definition can have either a bundle (a link to an AppBundle entity), or a src (Third party URL as a string) property. Both properties are mutually exclusive.

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)

• bundle: a link to an AppBundle if hosted on Contentful

• 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 App 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"
    }
  ]
}

An AppUpload is an entity that corresponds to a zip file containing all the assets of an app. The zip file cannot be accessed directly, but an AppUpload can be converted into an AppBundle entity.

App upload

AppBundle is an entity for hosting your app on Contentful. An AppBundle is a sub-resource of an AppDefinition. To create it you will need to create an AppUpload first and link it during the creation of the bundle.

The entity itself contains information about the files of the upload and the AppDefinition it relates to. Additionally, it is possible to add a comment to every bundle to identify it later on.

To enable an AppBundle, you need to link it in the AppDefinition entity with the bundle property. Make sure you remove the src property from the definition beforehand, if present, as these two properties are mutually exclusive (There can only be one way to host your app).

Limitations:

• Every AppBundle needs a valid index.html file at the root level of the folder.

• All internal links to your assets like stylesheets, JS files or others from the index.html must be relative paths.

AppDetails is an entity for storing additional information about an app.

This information is used to provide presentational and non-functional information about the app, such as specifying a custom icon.

The entity has a 1-to-1 relationship with the AppDefinition, but is optional and must be created manually.

Limitations:

• Custom icons cannot be larger than 128px x 128px and can only be in png or jpg format.

• Using the endpoints, icons can only be uploaded as base64 strings.

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 an existing AppDefinition. An app only receives events about content entities in a space environment of its installation.

App event subscription 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

• AppInstallation.create

• AppInstallation.update

• AppInstallation.delete

• Release.create

• Release.save

• Release.delete

• ReleaseAction.create

• ReleaseAction.execute

• ScheduledAction.create

• ScheduledAction.save

• ScheduledAction.delete

• ScheduledAction.execute

• BulkAction.create

• BulkAction.execute

AppSigningSecret is an entity that represents a symmetric key shared between Contentful and an app backend. Contentful uses this secret to sign requests sent to an app backend, which allows an app backend to verify that requests it receives are made by legitimate users of the app through Contentful.

Storing an AppSigningSecret for an app in Contentful enables two features:

1. All future app event requests will be automatically signed using the secret. The receiving backend can decide whether it wants to validate this signature or not, so enabling this should not have any immediate effect until used.
2. The signed request endpoint can be used to sign requests from the app frontend. There are helper functions in the App SDK that further simplify the process.

There are two constraints on the secret:

1. It must be exactly 64 characters long.

2. It must match this regular expression: /^[0-9a-zA-Z+/=_-]+$/. This also means secrets using the hex or base64 character set are allowed.

We recommend using a cryptographic pseudorandom number generator to generate a secret. See our guide on request verification for examples on how to generate a secret.

Only one AppSigningSecret per AppDefinition can be stored at any given time. Key rotation can be done by modifying the app backend to verify the request against both the old and a new secret, then saving the new secret to Contentful through this API. Contentful will then sign requests with the new secret, and the old secret can be removed from the app backend. See our guide on key rotation for examples.

A signed request is an object representing a HTTP request, that includes a signature header and some additional metadata.

Installing an app whose AppDefinition has an associated AppSigningSecret into a space allows users with access to that space to use the Content Management API to sign any request.

To do this, the full request needs to be submitted, and the computed signature will be returned, along with some additional headers. Including these headers in your subsequent request makes it possible for the receiving party to verify the request.

Requests expecting to be signed need to be in the following format:

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.

An AccessGrant is an entity type that indicates that an app described by some AppDefinition is able to be installed into a space in an Organization other than the Organization that owns the AppDefinition

An AccessGrant allows all organizations to install the AppDefinition it belongs to.

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 App 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, Locale, Tag, Task, Snapshot (only on master environment), and the app's own AppInstallation

• 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

• iat: Issued at - number representing a timestamp when the JWT was issued

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.

App Action is an entity that allows communication between apps. An app can expose actions that the other apps can call to trigger specific behaviors.

Actions are asynchronous and don't return a payload: they are used for single tasks like sending a notification. One can think about an AppAction as asynchronous function that doesn't return anything.

Notes

• ActionConsumer is a user or an app that triggers behaviours in other apps.

• ActionProvider is an app that exposes actions that other users or apps can trigger.

The diagram below displays an interaction between ActionProvider, ActionConsumer and CMA when an App Action is called.

In order to trigger an action on your app, a ActionConsumer needs to make a call to the CMA: Contentful will then send a signed request to your application. This comes with the following out-of-the-box features:

• Apps exposing actions are secured by request verification.

• Action parameters are pre-validated (with a provided schema) by Contentful.

• Actions can be triggered if and only if both ActionConsumer and ActionProvider have access to the same space-environment.

See an example implementation of an App Action in the code example below:

import createApp from 'imaginary-http-framework';
import { verifyRequest } from "@contentful/node-apps-toolkit";

import { sendNotification } from './service/imaginary';
import { signingSecret } from './secure-storage';

const app = createApp();

app.post('/send_notification', async (req, res, next) => {
    const canonicalRequest = {
        method: req.method,
        path. req.url,
        headers: req.headers,
        body: req.body,
    }

    if (!verifyRequest(signingSecret, canonicalRequest)) {
        next(new Error('409 - Conflict, signature does not match'));
        return;
    }

    const response = await sendNotification(req.body);

    res.send(200)
})

app.listen(3000)

Notes

When working with App Actions, consider the following:

• Actions can only be triggered by apps with app identities.

• Actions are asynchronous and don't yield a response.

• Only apps with signing secret can expose actions.

Errors

• 409 - Forbidden - This error is returned if signing secret is invalid or missing.

Calls to trigger actions are always mediated by Contenful. You can read the the previous section to understand why.

Errors

• 403 - Forbidden - This error is returned if the caller is not an installed app, or if the calling app is shared.

• 404 - NotFound - This error is returned if the action does not exist or the provider app is not installed in the current space-environment.

• 409 - Conflict - This error is returned if the provider has a missing or invalid signing secret.

Common use cases would require you to rewrite the same App Action over and over. With App Action Categories you can simply reference one of the pre made schemas, without having to redefine the same interface multiple times.

Let's assume your app needs to perform an operation and needs to trigger a notification to different services. Utilising categories, you can simply call App Actions whose category is Notification and ultimately integrate with all of them at once: you will only rely on the Notification and you are good to go.

Additionally, App Actions with some specific App Action Categories will show up in specific locations of the user interface.

App Action Categories are versioned in a semantic way: the first digit indicates a breaking change and the second digit all the other changes.

List of App Action categories

• Entries - An action that operates on a list of entry ids. Appears in Entry List.

• Notification - An action that sends notifications to an external service

• Custom - A custom action like deploying a website

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 Premium/Enterprise, Basic and Free plans. Premium/Enterprise and Basic customers can access historical usage data with API batch size of 45 days. Free plans 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.

Workflows definitions allow you to configure a pre-defined process for entries. Each workflow definition describes the schema for its workflows by a sequence of workflow steps which the executed workflows undergo.

Limitations

A workflow definition can define up to 20 steps. Defining more than 20 steps will result in a validation error.

The current maximum limit for workflow definitions is 20. If you lose access to the workflow API due to a price and package downgrade we will ensure that you can delete and complete existing workflows. An overview for our pricing and packaging can be found here.

Workflow definition schema

Besides the sequence of workflow steps, there are multiple properties to specify how workflows behave.

* The items in the list appliesTo must match the following shape:

{ linkType: "Entry", type: "Link", validations: [{ linkContentType: ["contentTypeA", "contentTypeB"] }] }

It is recommended to have only one item in appliesTo as well as only one item in validations. If you want to address multiple content types, you can do so by mentioning multiple within the list at linkContentType.

** In addition to the common sys properties, a workflow definition has the following extra sys properties

The flow type of a workflow definition

The property flowType controls to which step a user can move a workflow. It supports the follow two modes:

• no_restriction: Apply no restrictions when moving a workflow to another step.

• strict_neighbor: Enforce non-admin users to only move to the previous or the following step. The workflow can only be marked as 'complete' upon reaching the last step.

Automatically starting workflows

The property startOnEntityCreation will automatically start a workflow for newly created targeted entries. Each time you create an entry of a content type configured for this workflow definition, the workflow will start automatically. However, this does not mean that workflows are started for entries that were already created before setting this property to true.

Assigning multiple workflows to the same content type(s)

You can choose to configure multiple workflows for the same content type. This allows different teams working on the same content type to use dedicated workflows for their own review processes and governance.

Workflow step schema

A step within a workflow definition is described by the following properties.

* When leaving out the id in a POST/ PUT request for a workflow definition, you create a new step at that position in the list. When you define it (in a PUT request), you thereby update the existing step with that id.

Workflow step permission schema

In addition to the permission defined by a users role, a workflow step can restrict or grant permissions for selected users or teams. The permissions can only apply to a single active step in a workflow. The user restrictions in step permissions do not apply to organization or space admins. One permission must provide the following properties:

* There are two supported types for targeted resources:

• workflow_permission: Use this together with the action being edit to explicitly allow or deny who can move the workflow to another step.

• entity_permission: Grant or restrict permission to edit or publish the entry on which the workflow is being executed.

Workflow step action schema

When a workflow reaches a step, it will automatically trigger the actions defined for this step. Those actions can be one of the following three:

• Send an email to a set of users and teams. Additionally, you can also use any valid email address. The email notifies about the workflow being moved to this step. So far, the template is fixed and cannot be changed. There may be only one email action per step.

• Create an entry task with a customisable message and assign it one user or team. Optionally, you can define a due date. Please note that you need to have the tasks app installed. You can define up to three task actions per step.

• Send a custom message via Slack to a selected (public) channel about the workflow being moved to another step. Please note that you need to have the Slack app installed to use its app action. There may be only one Slack action per step.

Depending on the type, an action is defined by the following properties:

The workflow presents the relationship between the entry, the associated workflow definition, and the current workflow step. When a workflow is started on an entry, it will apply permission rules and automated actions which are defined in the related workflow definition.

Limitations

Though you may have more than one active workflow for each entry, creating a workflow for an entry will result in a validation error if there is already a workflow of the same type linked to the specified entry. For example, if you have a “Translation” workflow on an entry, you cannot start another “Translation” workflow until that one is completed or cancelled. However, you can start a “Legal Review” workflow in parallel with the “Translation” workflow for the same entry.

If you lose access to the workflow API due to a price and package downgrade we will ensure that you can delete and complete existing workflows. An overview for our pricing and packaging can be found here.

Workflow schema

* It is possible to start a workflow without entering a specific step right away. Thus, the stepId can be undefined directly after the creation of a new workflow.

** In addition to the common sys properties, a workflow has the following extra sys properties

We will be discontinuing the legacy Workflows version. To maintain the workflows from the legacy version, follow the migration guide below.

Who should migrate?

This guide is relevant for you if you have the Workflows legacy version configured to your space prior to March 1st, 2023.

The legacy version will stop being supported by Contentful on June 1st, 2023. If you would like to use the new Workflows app, you will need to migrate with support offered by Contentful in the process. Please refer to the guide below to discontinue using the legacy Workflows version.

Migration steps overview:

Upgrading to the Workflows app is accomplished by going through the following steps:

1. Ensure no tag-based permissions are associated with legacy Workflows tags.

2. Create a workflow configuration in the new Workflows app.

3. Begin migration of entries assigned to the legacy Workflow steps. There are two options for this: a. Manually remove all workflow tags from affected entries and reassign identical steps created in the new app. b. Use this script to help migrate the entry statuses.

   Note: If the legacy Workflows configuration is removed prior to this process, this option will no longer be available.

4. Verify the information from the legacy version is replicated in the new app.

   NOTE: Update any external systems that are relying on the legacy Workflows to the new app.

The workflows changelog is used to present the chronological list of records describing the history of workflow step changes for a single workflow which is linked to a specified entry. The changelog includes the associated entry, the new workflow step, and the timestamp of the event that occurred.

Workflows changelog record schema