Content Management API
Introduction
Contentful's Content Management API (CMA) helps you manage content in your spaces. To learn more about how to model your content, read our modeling guide.Note: You can use the CMA to deliver and manage content, but you shouldn't use it to deliver large amounts of content and instead use the Content Delivery API. The structure of responses from the CMA differs from the CDA as GET responses retrieve the entirety of items (i.e. all localized and unpublished content).
Basic API information
API Base URL
https://api.contentful.comThis is a read/write API
API rate limits Example 1
HTTP/1.1 2xx
X-Contentful-RateLimit-Reset: 0
API rate limits Example 1
HTTP/1.1 2xx
X-Contentful-RateLimit-Reset: 0
| Metric | Included units | Additional units | Maximum limit |
| Spaces | 1 Community space | No additional Community spaces can be added. Customers can add additional Medium and Large spaces as indicated on the pricing page | 20 |
| Users | 10 | $15/user/month | 25 |
| Metric | Maximum quota | Unit of measure |
| Total API calls (CMA, CPA, CDA) | 2,000,000 | Calls per month |
| Asset bandwidth | 0.75 | Terabytes (TBs) per month |
Authentication
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.
Content type
Entry
Resource IDs
When creating resources, you can specify an ID or let the API generate a random ID for you. If you choose an ID yourself it must adhere to the following rules:
It has a length between 1 and 64 characters.
It only includes alphanumeric characters, dots
., hyphens-or underscores_.
Represented as a regular expression, this is /^[a-zA-Z0-9-_.]{1,64}$/.
Updating content
Contentful doesn't merge changes made to content, so when updating content, you need to send the entire body of an entry. If you update content with a subset of properties, you will lose all existing properties not included in that update.You should always update resources in the following order:
Fetch current resource.
Make changes to the current resource.
Update the resource by passing the changed resource along with current version number.
This way no unseen changes are overridden and unexpected conflicts are unlikely to occur.Note: You can't update any of the sys property fields, including sys.id.
Updating and version locking
Contentful uses optimistic locking. When updating an existing resource, you need to specify its current version with the X-Contentful-Version HTTP header (this header is automatically set when using our official 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
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:
| Header | Description |
| X-Contentful-RateLimit-Second-Limit | The maximum amount of requests which can be made in a second. |
| X-Contentful-RateLimit-Second-Remaining | The remaining amount of requests which can be made until the next secondly reset. |
| X-Contentful-RateLimit-Reset | The number of seconds until the next request can be made. |
Here is a part of a Contentful Management API response example showing the headers for rate limiting:
Api Rate limits snippet
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
API rate limits Example 1
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
API rate limits Example 2
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
API rate limits Example 3
HTTP/1.1 429
X-Contentful-RateLimit-Reset: 900
Meaning: wait 15 minutes before making more requests (which frees up 9000 requests - 15 minutes later 9000 requests get freed up and so on).
Common Resource Attributes
Every resource returned by the API 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:
Reference
Spaces
Spaces collection
Spaces are containers for content types and content, and API clients can fetch data from one or more spaces. You can be a member of multiple organizations, and owner and admin roles in the organization can create spaces in organizations.When you sign up to Contentul for the first time, you create a new organization. When you're invited to an existing organization, you become a member of that organization.Note: If you have a single organization, any space you create will be automatically associated with that organization. If you're an admin or an owner in multiple organizations you need to pass the ID of the organization with the X-Contentful-Organization header that you want to create the space in.Note: If you are on our latest pricing model and have plans attached to your spaces, creating a new space via the API will assign the smallest available plan to it. If you've reached your limit of free spaces and have no payment details on file, you won't be able to create more spaces until you add payment details.
Test the snippet JS
const test = 'lets test some stuff';
console.log(test);
Test snippet JSON
{
check: true,
snippet: true,
}