CMA - Introduction

• AWS North America (AWS NA): https://api.contentstack.io/
• AWS Europe (EU): https://eu-api.contentstack.com/
• AWS Australia (AWS AU): https://au-api.contentstack.com/
• Azure North America (Azure NA): https://azure-na-api.contentstack.com/
• Azure Europe (Azure EU): https://azure-eu-api.contentstack.com/
• GCP North America (GCP NA): https://gcp-na-api.contentstack.com/
• GCP Europe (GCP EU): https://gcp-eu-api.contentstack.com/

Contentstack is a headless, API-first content management system (CMS) that provides everything you need to power your web or mobile properties. To learn more about Contentstack, visit our website or refer to our documentation site to understand what we do.

This document is a detailed reference to Contentstack’s Content Management API.

The Content Management API (CMA) is used to manage the content of your Contentstack account. This includes creating, updating, deleting, and fetching content of your account. To use the Content Management API, you will need to authenticate yourself with a Management Token or an Authtoken. Read more about it in Authentication.

We have created SDKs, API references, getting started guides, and sample apps for some of the popular languages and platforms. You can use them to build your own apps and manage your content from Contentstack.

Contentstack Management SDKs interact with the Content Management APIs and allow you to create, update, delete, and fetch content from your Contentstack account. They are read-write in nature.

You will find a list of all the available management SDKs under the Content Management SDKs section.

We provide Management SDKs for the following platform:

• JavaScript
• .NET
• Java
• Python

Contentstack provides token-based authentication that allows you to create, update, delete, and fetch the content of your Contentstack account. You can use either the stack’s Management Token, OAuth Token, or the user Authtoken, along with the stack API key, to make Content Management API requests. The API key is a unique key assigned to each stack.

Management Tokens are stack-level read-write tokens that allow making CMA requests without the need to provide user credentials. The Contentstack OAuth server generates access tokens (both App and User tokens), which client applications can employ to retrieve restricted data on behalf of the resource owner. However, Authtokens are user-specific tokens generated when user logs in to Contentstack. Read more about the different types of tokens.

• Pass the stack’s API key against the api_key parameter as header
• Pass the user Authtoken against the authtoken parameter as header

• Pass the stack’s API key against the api_key parameter as header
• Pass the user Management Token value against the authorization parameter as header

• Pass the stack’s API key against the api_key parameter as header for stack based APIs

• Pass the OAuth Token value against the authorization parameter as header

An Authtoken is a read-write token used to make authorized CMA requests, and it is a user-specific token. This means that your personal user details are attached to every API request that you make using the authtoken. So, if a person were to obtain access to your authtoken, and knows the Stack API key, this person would be able to make API requests that appeared to be coming from you.

Management Tokens, on the other hand, are stack-level tokens, with no users attached to them. They can do everything that authtokens can do. Since they are not personal tokens, no role-specific permissions are applicable to them. It is recommended to use these tokens for automation scripts, third-party app integrations, and for Single Sign On (SSO)-enabled organizations.

Contentstack OAuth employs the OAuth 2.0 protocol, enabling external applications to access Contentstack APIs on behalf of users. It issues access tokens (App & User tokens) to client applications, allowing them to retrieve restricted data from the Contentstack resource server without the need for the resource owner to share their credentials. Learn more about Contentstack OAuth and OAuth Scopes.

Authtoken lets you make almost all the Content Management requests, while with Management Tokens, you have a few limitations. For more information, read our Limitations of Management Tokens documentation.

Note When trying out POST/PUT calls, in addition to the API Key and Authtoken / Management token, you need to mandatorily pass Content-Type:application/json in the Header.

To retrieve the stack API key, perform the steps given below:

1. Go to your stack.
2. Navigate to Settings > Stack.
3. On the right-hand side of the page, under API Credentials, you will get the API Key of your stack.

NoteOnly the developers, admins and stack owners can view the API key.

To retrieve the authtoken, log in to your Contentstack account by using the "Log in to your account" request. This request will return the authtoken in the response body.

You can generate multiple authtokens by executing the "Log in to your account" request multiple times. These tokens do not have an expiration time limit. However, currently, there is a maximum limit of 20 valid tokens that a user can use per account at a time, to execute CMA requests. If you already have valid 20 tokens, creating a new authtoken will automatically cause the oldest authtoken to expire without warning.

For SSO-enabled organizations, the "Log in to your account" request will not return the user authtoken for users who access the organization through Identity Provider login credentials. Consequently, any requests that require user authtoken will not work. Only the owner of the organization and users with permission to access the organization without SSO can use the Content Management APIs. Learn more about REST API Usage.

To get the Management Token, perform the steps given below after logging into your Contentstack account:

1. Go to your stack.
2. Navigate to Settings > Tokens > Management Tokens.
3. From the list, pick the Management Token that you want.
   Read more about how you can create a new Management Token.

NoteOnly the stack Owner and Admin users can create Management Tokens.

You can generate multiple management tokens for a specific stack within your organization. However, there is a maximum limit of 10 valid tokens that can exist per stack at a time, to execute CMA requests. If you already have 10 valid tokens, creating a new management token will automatically cause the oldest management token to expire without warning.

To get the OAuth Token, perform the steps given within the Configuring Contentstack OAuth section after logging into your Contentstack account.

NoteOnly the organization Owner and Admin users can create OAuth Tokens.

Rate limit is the maximum number of requests you can make using Contentstack’s API in a given time period.

By default, the Contentstack Management API enforces the following rate limits:

• Read (GET) requests: 10 requests per second per organization.
• Write (POST/PUT/DELETE) requests: 10 requests per second per organization.

Your application will receive the HTTP 429 response code if the requests for a given time period exceed the defined rate limits.

NoteBulk actions do not follow the standard CMA rate limit of 10 requests per second. The default rate limit for bulk actions is 1 request per second i.e., in one second you can make only one bulk action API request.

We also have set a limit on stack creation. Organizations can create only one stack per minute.

The aforementioned limits are configurable depending on your plan. For more information, contact our support team.

To get the current rate limit status, you can check the returned HTTP headers of any API request. These rate limits are reset at the start of each time period.

• The base URL for Content Management API for different regions can be found in the Base URL section.
• The API version (in our case, 'v3') can be found in the URL, e.g. api.contentstack.io/v3/endpoint.
• Content Management API supports GET/POST/PUT/DELETE verbs or methods.
• URL paths are written in lower case.
• Query parameters and JSON fields use lower case, with underscores (_) separating words.
• The success/failure status of an operation is determined by the HTTP status it returns. Additional information is included in the HTTP response body.
• The JSON number type is bounded to a signed 32-bit integer.

If there is something wrong with the API request, Contentstack returns an error.

Contentstack uses conventional, standard HTTP status codes for errors, and returns a JSON body containing details about the error. In general, codes in the 2xx range signify success. The codes in the 4xx range indicate error, mainly due to information provided (for example, a required parameter or field was omitted). Lastly, codes in the 5xx range mean that there is something wrong with Contentstack’s servers; it is very rare though.

Let’s look at the error code and their meanings.

* Contentstack returns the 422 HTTP status code with the "UID is not valid" message when an entry doesn’t exist, has been deleted, or belongs to a different content type. To check if an entry has been deleted, first try retrieving it from the CDN, then from the origin server if needed. This error can also occur due to invalid query parameters, such as using an empty array with logical operators like $and. Always ensure your queries contain valid conditions. For example, {"$and": [{}, {}]} is not a valid query.

NoteThe error codes that we get in the JSON response are not HTTP error codes but are custom Contentstack error codes that are used for internal purposes.

Contentstack offers you a Postman Collection that helps you try out our Content Management API. You can download this collection, connect to your Contentstack account, and try out the Content Management API with ease.

Learn more about how to get started with using the Postman Collection for Contenstack Content Management API.

Contentstack provides the OpenAPI files of the Contentstack’s Content Management APIs (CMA) that you can use to try out Contentstack APIs on any OpenAPI platform such as Swagger. You can download the OpenAPI JSON file of the Content Management API and open it on Swagger Editor to start using it.

Learn more about how to get started with using the OpenAPI files for Contenstack Content Management API.