Content Management API

[API VERSION : 3.0.0]

Introduction

Base URL

For US region: https://api.contentstack.io/

For European region: https://eu-api.contentstack.com/

Overview

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.

Note: The Content Management APIs also include many GET requests. However, it is highly recommended that you always use the Content Delivery API to deliver content to your web or mobile properties.

Authentication

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 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. However, Authtokens are user-specific tokens generated when user logs in to Contentstack. Read more about the different types of tokens.

For API Key and Authtoken-based authentication

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

For API Key and Management Token-based authentication

  • 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

Authtokens vs Management Tokens

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.

Authtoken lets you make almost all the Content Management requests, while with Management Tokens, you have a few limitations (read them here).

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.

How to Get Stack API Key

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.

Note: Only the developers, admins and stack owners can view the API key.

How to Get Authtoken

To retrieve the authtoken, log in to your Contentstack account by using the "Log in to your account" request under "User Session". 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. Read more.

How to Get Management Tokens

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.

Note: Only 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.

Rate limiting

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.

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.

Headers Description
X-RateLimit-Limit The maximum number of request a client is allowed to make per second per organization.
X-RateLimit-Remaining The number of requests remaining in the current time period.

API conventions

  • The base URL for Content Management API is api.contentstack.ioand for the European region the base URL is eu-api.contentstack.com.
  • 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.

Errors

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.

HTTP status code Description
400 Bad Request The request was incorrect or corrupted.
401 Access Denied The login credentials are invalid.
403 Forbidden Error The page or resource that is being accessed is forbidden.
404 Not Found The requested page or resource could not be found.
412 Pre Condition Failed The entered API key is invalid.
422* Unprocessable Entity (also includes Validation Error and Unknown Field) The request is syntactically correct but contains semantic errors.
429 Rate Limit Exceeded The number of requests exceeds the allowed limit for the given time period. 
500 Internal Server Error The server is malfunctioning and is not specific on what the problem is.
502 Bad Gateway Error A server received an invalid response from another server.
504 Gateway Timeout Error A server did not receive a timely response from another server that it was accessing while attempting to load the web page or fill another request by the browser.

* Contentstack returns the 422 HTTP status code for an error along with the "UID is not valid" message in the response body either when an entry doesn’t exist within the stack, has been deleted from the content type, or exists within a different content type. As the entry has been deleted or unpublished, the Content Delivery Network (CDN) cannot identify the specified entry UID through the cache servers. To check whether the entry has been deleted, try retrieving the entry from CDN first. If the API request fails to retrieve the entry from CDN, then make an API request to the Origin server to check whether the entry exists.

Postman Collection

Introduction to Contentstack Postman Collection

The Contentstack Postman collection is a set of preconfigured REST API requests that will make it easy for you to get started with the Contentstack APIs and try out our API requests through the popular Postman REST client.

Install Postman

To use the Contentstack Postman Collection you will need to have the Postman desktop app installed on your device.

Note: If you have already installed Postman for your device, go to the Download Latest Postman Collection for Contentstack section.

Postman is available for Windows (x32), Windows (x64), Mac, and Linux environments.

Download Latest Postman Collection for Contentstack

Once you have installed Postman for your device, click on the following button to download and install our latest Postman collection that covers all the Content Management API endpoints for Contentstack.

Note: The Contentstack Postman collection does not support the now deprecated Postman Chrome extension. Make sure you have installed the latest version of the Postman desktop app.

After selecting the appropriate variant of Postman, the collection will open the Postman app and appear in the left pane:

Collection appears on the left pane_CMA.png

Note: For Windows, downloading the collection doesn't download the environment automatically due to the larger size of the environment file. Consequently, Windows users need to download the Content Management API - Environment file manually and import it in their Postman environment.

Download Collection from GitHub Page

We have also hosted our Postman collection on GitHub. You can follow the steps mentioned in the Readme file to download and start using it.

You can also choose to watch the latest Postman collection to get notifications of new releases or updates.

To do so, click on the following Watch button and select Watching.

Configure Environment Variables

When you download and install the latest version of the Content Management API (CDA) Postman Collection, you also download and import the respective environment along with the environment variables.

Note: For Windows, downloading the collection doesn't download the environment automatically due to the larger size of the environment file. Consequently, Windows users need to download the Content Management API - Environment file manually and import it in their Postman environment.

Once your Environment is imported, next you need to set your Contentstack account specific values.

Note: As these environment variables are referenced across multiple API requests, once you set the variables, it becomes a lot more convenient to make repeated use of the Postman Collection.

Some of the important variables that you need to set are as follows:

Environment Variable Value
base_url api.contentstack.io
api_key your_stack_api_key
authorization your_management_token

Note: The Contentstack Postman Collection will require a valid Management token to make API calls. Check out the Authentication section for more details.

If you want to add your own environment variables, you can follow the procedure in the next section.

Add Other Environment Variables

To add any new environment variables for your Postman collection, perform the following steps:

  1. Identify the environment variables that you want to define.
  2. In the top right corner of Postman, click on the “Manage Environments” settings cog.
    Click on the Manage Environments cog_CMA.png

  3. Click on your environment Content Management API Environment.
  4. In the VARIABLE field, enter the name of the environment variable.
    In the INITIAL VALUE field, enter your Contentstack-account-specific value that will replace the variable when the call is made.
    Manage Environments_CMA.png

  5. Once you have defined your variables, click on Update.

Update Environment Variables

With every new API request added, we update our environment file. So, to get the latest environment variables, you need to download the collection along with the updated environment file again, compare your existing environment with the latest environment, identify and add the new variables to your existing environment.

Make an API Request in Postman

With the Contentstack Postman Collection loaded into the Postman app (on the left pane) and the environment created, you can now make API requests to the Contentstack API via Postman.

To make an API request, perform the following steps:

  1. Select the respective environment (see the following screenshot.)
  2. Select an API Request from the Contentstack Postman Collection. In this example, we will use the Get user request which is a part of the Users folder.

    Note: If you want to make changes to your parameters or want to add parameters of your own, you can do it here.

  3. Next, click on Send at the top right to make the API request.How to make an API Request_CMA.png

The API call should return with a response under the Body tab in the bottom half of the screen.

Response Body of Your API Request_CMA.png

Secure your API Keys and Tokens

We strongly advise against storing your API keys and tokens in your collection permanently. If you or someone else shares the collection by mistake, other users will be able to export it along with these keys.

We recommend that you provide your Contentstack account-specific API keys and tokens in your environment or directly to the sample requests.

Users using Authtoken

For users who use authtoken to authenticate their calls, when you make the Log in to your account API Request, your authtoken will be saved in cookies.

If you want to prevent this action, perform the steps given below:

  1. Click on Cookies on the far right corner.
  2. In the MANAGE COOKIES modal, click on Whitelist Domains at the bottom left.
  3. Add api.contentstack.io and click Add.

This will whitelist this domain and will allow you to access cookies of this domain in scripts programmatically.

Note: To avoid this situation, we recommend you to use the stack’s Management Token along with the stack API key to make valid Content Management API requests. For more information, refer to Authentication.

Postman Collection Updates

We keep our Postman Collection updated. To get the latest version of our Postman Collection, all you need to do is to download the Postman Collection along with the updated environment again and you are good to go.

You can also choose to watch for the latest Postman Collection updates on our GitHub repository and get notifications of new releases or updates to the repository. The GitHub Readme doc will help you with the steps that you need to follow.

Reference

Users

All accounts registered with Contentstack are known as Users. A stack can have many users with varying permissions and roles. Read Users to learn more.

Note: Before executing any calls, retrieve the authtoken by authenticating yourself via the Log in call of User Session. The authtoken is returned in the 'Response' body of the Log in call and is mandatory in all of the calls. Example: blt3cecf75b33bb2ebe

Get User

Get user

Try

The Get user call returns comprehensive information of an existing user account. The information returned includes details of the stacks owned by and shared with the specified user account.

Update User

Update user

Try

The Update User API Request updates the details of an existing user account. Only the information entered here will be updated, the existing data will remain unaffected.

When executing the API call, under the 'Body' section, enter the information of the user that you wish to update. This information should be in JSON format.

Note: To update the role of an existing user, refer the Update Existing User Role API Request.

Activate User

Activate a user account

Try

The Activate a user account call activates the account of a user after signing up. For account activation, you will require the token received in the activation email.

Request Password

Request for a password

Try

The Request for a password call sends a request for a temporary password to log in to an account in case a user has forgotten the login password.

Using this temporary password, you can log in to your account and set a new password for your Contentstack account.

In the 'Body' section, provide the user's email address in JSON format.

Reset Password

Reset password

Try

The Reset password call sends a request for resetting the password of your Contentstack account.

When executing the call, in the 'Body' section, you need to provide the token that you receive via email, your new password, and password confirmation in JSON format.

Note: Before using this call, you need to run the 'Request Password' call to receive the reset password token in your registered email address.

User Session

User session consists of calls that will help you to sign in and sign out of your Contentstack account.

Logging in/out

Log in to your account

Try

The Log in to your account request is used to sign in to your Contentstack account and obtain the authtoken.

Note: The authtoken is a mandatory parameter when executing Content Management API calls. However, when executing Content Delivery API calls, pass the environment-specific delivery token against the access_token key.

In the 'Body' section, enter the user credentials in JSON format. The JSON query will include the email address, the Contentstack user account password, and the two-factor authentication token (if enabled) received in the Authy app or SMS.

For SSO-enabled organizations, the ‘Log in to your account’ request will not return the user authtoken for users. In this case, you can try out the following:

  • The owner of an organization can access the SSO-enabled organization through Contentstack credentials and retrieve the user authtoken to make Content Management API requests.
  • Disable 'Strict Mode' for an SSO-enabled organization, and users who have the ability to access their organization through Contentstack credentials can retrieve the authtoken to make Content Management API requests.

For more details, refer the REST API Usage - Content Management API section in the Single Sign-On page.

Log out of your account

Try

The Log out of your account call is used to sign out the user of Contentstack account.

Organizations

Organization is the top-level entity in the hierarchy of Contentstack, consisting of stacks and stack resources, and users. Organization allows easy management of projects as well as users within the Organization.

Read more about Organizations.

Get All Organizations

Get all Organizations

Try

The Get all organizations call lists all organizations related to the system user in the order that they were created.

Get Single Organization

Get a single Organization

Try

The Get a single organization call gets the comprehensive details of a specific organization related to the system user.

Organization Roles

Get all roles in an Organization

Try

The Get all roles in an organization call gives the details of all the roles that are set to users in an Organization.

When executing the API call, provide the Organization's UID.

Organization Users

Add users to Organization

Try

The Add users to organization call allows you to send invitations to add users to your organization. Only the owner or the admin of the organization can add users.

When executing the API call, provide the Organization UID.

Resend pending Organization invitation

Try

The Resend pending organization invitation call allows you to resend Organization invitations to users who have not yet accepted the earlier invitation. Only the owner or the admin of the Organization can resend the invitation to add users to an Organization.

When executing the API call, provide the Organization UID.

Get all Organization invitations

Try

The Get all organization invitations call gives you a list of all the Organization invitations. Only the owner or the admin of the Organization can resend the invitation to add users to an Organization.

When executing the API call, provide the Organization UID.

Transfer Organization Ownership

Transfer Organization ownership

Try

The Transfer organization ownership call transfers the ownership of an Organization to another user. When the call is executed, an email invitation for accepting the ownership of a particular Organization is sent to the specified user.

Once the specified user accepts the invitation by clicking on the link provided in the email, the ownership of the Organization gets transferred to the new user. Subsequently, the previous owner will no longer have any permission on the Organization.

When executing the API call, provide the Organization UID.

Organization Stacks

Get all stacks in an Organization

Try

The Get all stacks in an organization call fetches the list of all stacks in an Organization.

When executing the API call, provide the Organization UID.

Organization Logs

Get organization log details

Try

The Get organization log details request is used to retrieve the audit log details of an organization.

You can apply queries to filter the results. Refer to the Queries section for more details.

Tip: This request returns only the first 25 audit log items of the specified organization. If you get more than 25 items in your response, refer the Pagination section to retrieve all the log items in paginated form.

Get organization log item

Try

The Get organization log item request is used to retrieve a specific item from the audit log of an organization.

Stacks

A stack is a space that stores the content of a project (a web or mobile property). Within a stack, you can create content structures, content entries, users, etc. related to the project. Read more about Stacks.

Get Single Stack

Get a single stack

Try

The Get a single stack call fetches comprehensive details of a specific stack.

Note: For SSO-enabled organizations, it is mandatory to pass the organization UID in the header.

Get All Stacks

Get all stacks

Try

The Get all stacks call fetches the list of all stacks owned by and shared with a particular user account.

Note: For SSO-enabled organizations, it is mandatory to pass the organization UID in the header.

Create Stack

Create stack

Try

The Create stack call creates a new stack in your Contentstack account.

In the 'Body' section, provide the schema of the stack in JSON format.

Note: At any given point of time, an organization can create only one stack per minute.

Update Stack

Update stack

Try

The Update stack call lets you update the name and description of an existing stack.

In the 'Body' section, provide the updated schema of the stack in JSON format.

Warning: The master locale cannot be changed once it is set while stack creation. So, you cannot use this call to change/update the master language.

Delete stack

Delete stack

Try

The Delete stack call is used to delete an existing stack permanently from your Contentstack account.

Get all users

Get all users of a stack

Try

The Get all users of a stack call fetches the list of all users of a particular stack

Update Existing User Role

Update User Role

Try

The Update User Role API Request updates the roles of an existing user account. This API Request will override the existing roles assigned to a user. For example, we have an existing user with the "Developer" role, and if you execute this API request with "Content Manager" role, the user role will lose "Developer" rights and the user role be updated to just "Content Manager".

When executing the API call, under the 'Body' section, enter the UIDs of roles that you want to assign a user. This information should be in JSON format.

Transfer Stack Ownership

Transfer stack ownership to other users

Try

The Transfer stack ownership to other users call sends the specified user an email invitation for accepting the ownership of a particular stack.

Once the specified user accepts the invitation by clicking on the link provided in the email, the ownership of the stack gets transferred to the new user. Subsequently, the previous owner will no longer have any permission on the stack.

In the 'Body' section, you need to provide the email address of the user to whom you wish to transfer the ownership of the stack in JSON format.

Accept Stack Ownership

Accept stack owned by other user

Try

The Accept stack owned by other user call allows a user to accept the ownership of a particular stack via an email invitation.

The email invitation includes a link (i.e., /stack/accept_ownership/{ownership_token}?api_key={api_key}&uid={user_uid} ) that consists of the ownership token, the API key, and user uid.

Once the user accepts the invitation by clicking on the link, the ownership is transferred to the new user account. Subsequently, the user who transferred the stack will no longer have any permission on the stack.

When executing the API call, in the 'URI Parameters' section, you need to provide the ownership token and the user uid that you received in the invitation mail.

Stack Settings

Get stack settings

Try

The Get stack settings call retrieves the configuration settings of an existing stack.

Add stack settings

Try

The Add stack settings call lets you add settings for an existing stack.

Reset stack settings

Try

The Reset stack settings call resets your stack to default settings, and additionally, lets you add parameters to or modify the settings of an existing stack.

Share Stack

Share a stack

Try

The Share a stack call shares a stack with the specified user to collaborate on the stack.

In the 'Body' section, you need to provide the email ID of the user with whom you wish to share the stack along with the role uid that you wish to assign the user.

Unshare Stack

Unshare a stack

Try

The Unshare a stack call unshares a stack with a user and removes the user account from the list of collaborators. Once this call is executed, the user will not be able to view the stack in their account.

In the 'Body' section, you need to provide the email ID of the user from whom you wish to unshare the stack.

Content Types

Content type defines the structure or schema of a page or a section of your web or mobile property. To create content for your application, you are required to first create a content type, and then create entries using the content type. Read more about Content Types.

Get All Content Types

Get all content types

Try

The Get all content types call returns comprehensive information of all the content types available in a particular stack in your account.

Note: You need to use either the stack’s Management Token or the user Authtoken (any one is mandatory), along with the stack API key, to make a valid Content Management API request. Read more about authentication.

When executing the API call, you can add queries to extend the functionality of this API call.

Tip: If any of your content types contains a Global field and you wish to fetch the content schema of the Global field, then you need to pass theinclude_global_field_schema:true parameter. This parameter helps return the Global field's schema along with the content type schema.

Under the 'URI Parameters' section, insert a parameter named query and provide a query in JSON format as the value. (To learn more about the queries, refer to the Queries section of the Content Delivery API doc.)

Note: This API request will return a maximum of 100 content types. To retrieve the next batch of content types, make use of the skip parameter (or refer Pagination for more details).

Get Single Content Type

Get a single content type

Try

The Get a single content type call returns information of a specific content type.

Note: You need to use either the stack’s Management Token or the user Authtoken (any one is mandatory), along with the stack API key, to make a valid Content Management API request. Read more about authentication.

Enter the version of the content type of which you want to retrieve the details as a query parameter. If no version is specified, you will get the latest version of the content type.

Note: The schema of the content type returned will depend on the provided version. If no version is specified, you will get the latest version of the content type.

To learn more about the queries, refer to the Queries section of the Content Delivery API doc.

Tip: If any of your content types contains a Global field and you wish to fetch the content schema of the Global field, then you need to pass theinclude_global_field_schema:true parameter. This parameter helps return the Global field's schema along with the content type schema.

Create Content Type

Create a content type

Try

The Create a content type call creates a new content type in a particular stack of your Contentstack account.

In the “Body” section, you need to provide the complete schema of the content type. You can refer the JSON schema for creating a content type document to know how you can add fields into your content type through API.

Note: You need to use either the stack’s Management Token or the user Authtoken (any one is mandatory), along with the stack API key, to make a valid Content Management API request. Read more about Authentication.

To mark a field as non-unique, you need to set the unique parameter to false. For example, to remove the unique constraint on the default 'title' field, you need to update the JSON schema of the title field as follows:

{
    "display_name": "Title",
    "uid": "title",
    "data_type": "text",
    "mandatory": true,
    "unique": false,
    "field_metadata": {
      "_default": true
    },
    "multiple": false
}

Update Content Type

Update Content Type

Try

The Update Content Type call is used to update the schema of an existing content type.

Note: Whenever you update a content type, it will auto-increment the content type version.

When executing the API call, in the “URI Parameters” section, provide the uid of your content type.

In the “Body” section, you need to provide the updated schema of your content type. You can refer the JSON schema for creating a content type document to know how you can add/update fields in your content type through API.

Note: You need to use either the stack’s Management Token or the user Authtoken (any one is mandatory), along with the stack API key, to make a valid Content Management API request. Read more about authentication.

Set Field Visibility Rule for Content Type

Set Field Visibility Rule for Content Type

Try

The Set Field Visibility Rule for Content Type API request lets you add Field Visibility Rules to existing content types. These rules allow you to show and hide fields based on the state or value of certain fields.

Field Visibility Rules can be set while creating your content type (via UI, only after you’ve added all the required fields to the content type and saved it) or while editing a content type (both via UI and API).

To set a Field Visibility Rule, you need to add the following code snippet in the Request body of the content type:

{
    ...
    "content_type": {
        "field_rules": [{
            "conditions": [{
                "operand_field": "operand_field_uid",
                "operator": "equals",
                "value": "value_corresponding_to_operator"
            }],
            "match_type": "all",
            "actions": [{
                "action": "show",
                "target_field": "target_field_uid"
            }]
        }]
    }
    ...
}

Let’s look at the keys used in the above code snippet:

  • operand_field: Pass the UID of the Operand field (operand_field_uid) i.e., the field on which you want to set the condition.
  • operator: Pass the operator that you want to act on the operand field. Here’s the list of operators that are applicable based on the data type of your operand field:

    Data Types Operations
    Text matches, does_not_match, starts_with, ends_with, contains
    Number equals, not_equals, less_than, greater_than, less_than_or_equals, greater_than_or_equals
    Date equals, not_equals, before_date, after_date
    Boolean is, is_not
    Select is, is_not
    Reference is, is_not
  • value: Pass the value that is corresponding to the operator that you have used. Note that for Date data type, you need to pass the date in ISO format.
  • match_type: You need to pass either all or any depending on whether you want all your conditions or any one of your conditions to be met.
  • action: You need to pass either show or hide depending on whether you want to show or hide the Target field.
  • target_field: Pass the UID of the Target field (target_field_uid) i.e., the field on which you want to perform the action.

For more details, check out the Define Conditions section when adding a Field Visibility Rule.

Delete Content Type

Delete Content Type

Try

The Delete Content Type call deletes an existing content type and all the entries within it.

When executing the API call, in the “URI Parameters” section, provide the UID of your content type.

Note: You need to use either the stack’s Management Token or the user Authtoken (any one is mandatory), along with the stack API key, to make a valid Content Management API request. Read more about Authentication.

Content Type References

Get all references of content type

Try

The Get all references of content type call will fetch all the content types in which a specified content type is referenced.

Note: You need to use either the stack’s Management Token or the user Authtoken (any one is mandatory), along with the stack API key, to make a valid Content Management API request. Read more about authentication.

Additionally. to fetch all Global fields in which the specified content type is referenced, you need to pass include_global_fields as a query parameter. Set this parameter to true to include the Global fields along with the content types.

Export Content Type

Export a content type

Try

This call is used to export a specific content type and its schema. The data is exported in JSON format.

However, please note that the entries of the specified content type are not exported through this call.

The schema of the content type returned will depend on the version number provided.

Note: You need to use either the stack’s Management Token or the user Authtoken (any one is mandatory), along with the stack API key, to make a valid Content Management API request. Read more about authentication.

Import Content Type

Import a content type

Try

The Import a content type call imports a content type into a stack by uploading JSON file.

Note: You need to use either the stack’s Management Token or the user Authtoken (any one is mandatory), along with the stack API key, to make a valid Content Management API request. Read more about authentication.

Tip: You can try the call manually in any REST API client, such as Postman. You can export the required content type's JSON file, make the necessary changes to the data and then import the content type. While importing, you need to pass a form-data parameter named content_type and select the input type as 'File'. Then, select the JSON file of the content type that you wish to import.

Global Fields

A Global field is a reusable field (or group of fields) that you can define once and reuse in any content type within your stack. This eliminates the need (and thereby time and efforts) to create the same set of fields repeatedly in multiple content types. Read more about Global fields.

Get All Global Fields

Get all global fields

Try

The Get all global fields call returns comprehensive information of all the global fields available in a particular stack in your account.

Note: You need to use either the stack’s Management Token or the user Authtoken (any one is mandatory), along with the stack API key, to make a valid Content Management API request. Read more about authentication.

Get Single Global Field

Get a single global field

Try

The Get a single global field request allows you to fetch comprehensive details of a specific global field.

When executing the API call, in the 'URI Parameters' section, provide the unique ID of your global field.

Note: You need to use either the stack’s Management Token or the user Authtoken (any one is mandatory), along with the stack API key, to make a valid Content Management API request. Read more about authentication.

Create Global Field

Create a global field

Try

The Create a global field request allows you to create a new global field in a particular stack of your Contentstack account. You can use this global field in any content type within your stack.

Note: Only the stack owner, administrator, and developer can create global fields.

Note: You need to use either the stack’s Management Token or the user Authtoken (any one is mandatory), along with the stack API key, to make a valid Content Management API request. Read more about authentication.

Update Global Field

Update a global field

Try

The Update a global field request allows you to update the schema of an existing global field.

When executing the API call, in the 'URI Parameters' section, provide the unique ID of your global field.

Note: You need to use either the stack’s Management Token or the user Authtoken (any one is mandatory), along with the stack API key, to make a valid Content Management API request. Read more about authentication.

Delete Global Field

Delete global field

Try

The Delete global field request allows you to delete a specific global field.

Warning: If your Global field has been referred within a particular content type, then you will need to pass an additional query parameter force:true to delete the Global field.

When executing the API call, in the 'URI Parameters' section, provide the unique ID of your global field.

Note: You need to use either the stack’s Management Token or the user Authtoken (any one is mandatory), along with the stack API key, to make a valid Content Management API request. Read more about authentication.

Import Global Field

Import a global field

Try

The Import a global field call imports a global field into a stack.

Note: You need to use either the stack’s Management Token or the user Authtoken (any one is mandatory), along with the stack API key, to make a valid Content Management API request. Read more about authentication.

To import, you need to provide/upload a JSON file that contains the schema of the global field that you wish to import.

Tip: You can try the call manually in any REST API client, such as Postman, by passing a 'Body' parameter named global_field and selecting the input type as 'File'. Then, select the JSON file of the global field that you wish to import.

Export Global Field

Export a global field

Try

This request is used to export a specific global field and its schema. The data is exported in JSON format.

Note: You need to use either the stack’s Management Token or the user Authtoken (any one is mandatory), along with the stack API key, to make a valid Content Management API request. Read more about authentication.

Entries

An entry is the actual piece of content created using one of the defined content types. Read more about Entries.

Get all Entries

Get all entries

Try

The Get all entries call fetches the list of all the entries of a particular content type. It also returns the content of each entry in JSON format. You can also specify the environment and locale of which you wish to get the entries.

You can add queries to extend the functionality of this API call. Under the URI Parameters section, insert a parameter named query and provide a query in JSON format as the value.

To learn more about the queries, refer to the Queries section of the Content Delivery API doc.

Tip: This request returns only the first 100 entries of the specified content type. If you want to fetch entries other than the first 100 in your response, refer the Pagination section to retrieve all your entries in paginated form. Also, to include the publish details in the response, make use of the include_publish_details parameter and set its value to ‘true’. This query will return the publish details of the entry in every environment along with the version number that is published in each of the environment.

Get a Single Entry

Get a single entry

Try

The Get a single entry request fetches a particular entry of a content type.

The content of the entry is returned in JSON format. You can also specify the environment and locale of which you wish to retrieve the entries.

Tip: To include the publish details in the response, make use of the include_publish_details parameter and set its value to ‘true’. This query will return the publish details of the entry in every environment along with the version number that is published in each of the environment.

Also, if no version is mentioned, this request will retrieve the latest published version of the entry. To retrieve a specific version, make use of the version parameter.

Create an Entry

Create an entry

Try

The Create an entry call creates a new entry for the selected content type.

When executing the API call, in the 'Body' section, you need to provide the content of your entry based on the content type created.

If you need to create an entry that contains an asset file, you need to provide the asset UID(s) in the ‘Body’ section. If you want to add only one file, enter a single UID (file_field_uid in the below code). For multiple asset files, enter the asset files’ UIDs (file_field_uid_multiple in the below code) in an array.

The JSON schema should be as follows:

{
    "entry": {
        "title": "<<title>>",
        "url": "<<url>>",
        "file_field_uid": "<<asset_uid>>",    // Simple ‘File’ field
        "file_field_uid_multiple": ["<<asset_uid1>>", "<<asset_uid2, ...>>"],
                        // ‘File’ field marked ‘Multiple’
    }
}

If you want to add your asset file within a Rich Text Editor, use the following JSON schema:

{
    "entry": {
        "title": "<<title>>",
        "url": "<<url>>",
        "rte_uid": "<p><img src=\"asset_URL\" data-sys-asset-uid=\"asset_UID\" alt=\"Alternative_Text\"></p>"
    }
}

Update an Entry

Update an entry

Try

The Update an entry call lets you update the content of an existing entry.

Passing the locale parameter will cause the entry to be localized in the specified locale.

Note: The Update an entry call does not allow you to update the workflow stage for an entry. To update the workflow stage for the entry, use the Set Entry Workflow Stage call.

Atomic Updates to Entries

Atomic operations are particularly useful when we do not want content collaborators to overwrite data. Though it works efficiently for singular fields, these operations come handy especially in case of fields that are marked as “Multiple”.

To achieve data atomicity, we have provided support for following atomic operators: PUSH, PULL, UPDATE, ADD, and SUB.

PUSH Operation

PUSH Operation

Try

The PUSH operation allows you to “push” (or append) data into an array without overriding an existing value.

For example, you have an entry with a Number field (named “Multiple Number”), marked as “Multiple” and with the data, “1,” “4,” “5,” and you need to add “2” and “3” to it. In this case, you need to use the PUSH operation as follows:

{
    "entry": {
        "multiple_number": {
            "PUSH": {
                "data": [
                    2,
                    3
                ]
            }
        }
    }
}

Say you need to push specific data (say “abc”) into a field named “Demo Field” which is within a “Group” field marked as “Multiple”. You need to use the “PUSH” operator as follows:

{
    "entry": {
        "multiple_group": {
            "PUSH": {
                "data": {
                    "demo_field": "abc"
                }
            }
        }
    }
}
PULL Operation
PULL Operation

Try

The PULL operation allows you to pull data from an array field based on a query passed.

For example, you have an entry with a “Number” field named “Multiple Number” which has the values, “1,” “2,” “3,” “4,” and “5”, and you need to remove “2” and “ 3”. You need to use the PULL operation as follows:

{
    "entry": {
        "multiple_number": {
            "PULL": {
                "query": {
                    "$in": [
                        2,
                        3
                    ]
                }
            }
        }
    }
}

Another example is if you need to pull specific field data from a field (say a “Group” field) marked as “Multiple,” where the field name is “Demo Field” and the specific value to be pulled is “abc”. You need to use the “PULL” operator as follows:

{
    "entry": {
        "multiple_group": {
            "PULL": {
                "query": {
                    "demo_field": {
                        "$in": ["abc"]
                    }
                }
            }
        }
    }
}

Note: Here are certain limitations to the PULL request:
1. Currently, a PULL operation on multiple fields will retrieve the result of only ONE field i.e., if you include multiple fields in your PULL request, you will be able to retrieve the data of only the first mentioned field.
2. PULL query does not work on Nested Group fields.

UPDATE Operation
UPDATE Operation

Try

The UPDATE operation allows you to update data at a specific index. This operation works for both singular fields and fields marked “Multiple”.

For example, you have an entry with a “Number” (named “Multiple Number”) field which has the values, “6,” “2,” “3,” “4,” and “5”, and you need to replace the number at the first index (a[0]) i.e., “6” with “1”. In this case, you need to use the UPDATE operation as follows:

{
    "entry": {
        "multiple_number": {
            "UPDATE": {
                "index": 0,
                "data": 1
            }
        }
    }
}

Atomic Operators for Number Fields

Contentstack provides support for atomic operators that will specifically help you to work with “Number” fields. These atomic operators include ADD and SUB.

ADD Operation
ADD Operation

Try

The ADD operation reads the latest value of a “Number” field and increments it by a numeric passed along with the operator. The increment occurs irrespective of what the current value of the field is.

For example, you have a “Number” field and you want to increment the value of the field by one. In this case, you need to use the "ADD":1 operation. This operation reads the latest value of the field, increments it by 1, and replaces the existing value of the field with the new value.

SUB Operation
SUB Operation

Try

The SUB operation works the opposite of ADD. It reads the latest value of a “Number” field and decrements it by a numeric value passed along with the operator.

For example, you have a “Number” field and you want to decrease the value of the field by one. In this case, you need to use the "SUB":1 operation. This operation reads the latest value of the field, decrements it by 1, and replaces the existing value of the field with the new value.

Delete an Entry

Delete an entry

Try

The Delete an entry request allows you to delete a specific entry from a content type. This API request also allows you to delete single and/or multiple localized entries.

Note: In the Header, you need to use either the stack Management Token (recommended) or the user Authtoken, along with the stack API key, to make valid Content Management API requests. For more information, refer to Authentication.

This API Request supports the following actions as well:

  • Delete specific localized entry: For this request, you need to only specify the locale code of the language in the locale query parameter. If the locale parameter is not been specified, by default, the master language entry will be deleted.
  • Delete master language along with all its localized entries: For this request, instead of the locale query parameter, you need to pass the delete_all_localized:true query parameter.

    Note: The delete_all_localized parameter will work only if you are deleting localized versions from the master language.

  • Delete multiple localized entry: Additionally, you can delete specific localized entries by passing the locale codes in the Request body using the locales key as follows:
    {
      "entry": {
        "locales": ["hi-in", "mr-in", "es"]
      }
    }

Entry Version Naming

Version naming allows you to assign a name to a version of an entry for easy identification. For more information, refer the documentation.

Set Version Name for Entry

Try

The Set Version Name for Entry request allows you to assign a name to a specific version of an entry.

In the request body, you need to specify the version name to be assigned and the locale of the entry.

Tip: You can add an additional parameter force:true to force update the version name of the master entry.

Get Details of All Versions of an Entry

Try

The Get Details of All Versions of an Entry request allows you to retrieve the details of all the versions of an entry.

The version details returned include the actual version number of the entry; the version name along with details such as the assigned version name, the UID of the user who assigned the name, and the time when the version was assigned a name; and the locale of the entry.

Note: If an entry is unlocalized, the version details of entries published in the master locale will be returned.

Delete Version Name of Entry

Try

The Delete Version Name of Entry request allows you to delete the name assigned to a specific version of an entry. This request resets the name of the entry version to the version number.

Entry References

Get references of an entry

Try

The Get references of an entry call returns all the entries of content types that are referenced by a particular entry.

Entry Languages

Get languages of an entry

Try

The Get languages of an entry call returns the details of all the languages that an entry exists in.

Localize an Entry

Localize an entry

Try

The Localize an entry request allows you to localize an entry i.e., the entry will cease to fetch data from its fallback language and possess independent content specific to the selected locale.

In the "Body" parameter, you need to provide the content of your entry based on the content type.

Note: This request will only create the localized version of your entry and not publish it. To publish your localized entry, you need to use the Publish an entry request and pass the respective locale code in the locale={locale_code} parameter.

Refer the Localization docs for more information.

Unlocalize Entry

Unlocalize an entry

Try

The Unlocalize an entry request is used to unlocalize an existing entry. Read more about Unlocalization.

Export Entry

Export an entry

Try

The Export an entry call is used to export an entry. The exported entry data is saved in a downloadable JSON file.

Import Entry

The Import Entry calls given below help you to import entries by uploading JSON files.

Tip: You can try the call manually in any REST API client, such as Postman. You can export the required entry's JSON file, make the necessary changes to the data and then import the entry. While importing, you need to pass a form-data parameter named entry and select the input type as 'File'. Then, select the JSON file of the entry that you wish to import.

Import an entry

Try

The Import an entry call is used to import an entry. To import an entry, you need to upload a JSON file that has entry data in the format that fits the schema of the content type it is being imported to.

Import an existing entry

Try

The Import an existing entry call will import a new version of an existing entry. You can create multiple versions of an entry.

Publish Entry

Publish an entry

Try

The Publish an entry request lets you publish an entry either immediately or schedule it for a later date/time.

In the 'Body' section, you can specify the locales and environments to which you want to publish the entry. When you pass locales in the "Body", the following actions take place:

  • If you have not localized your entry in the above-mentioned locales, the Master Locale entry gets localized in those locales and are published
  • If you have localized your entry in the above-mentioned locales, the existing localized content is published.

The locale and environment details should be specified in the ‘entry’ parameter. However, if you do not specify any source locale(s), it will be published in the master locale automatically.

Along with the above details, you also need to mention the master locale and the version number of your entry that you want to publish.

In case of Scheduled Publishing, add the scheduled_at key and provide the date/time in the ISO format as its value. Example: "scheduled_at":"2016-10-07T12:34:36.000Z"

Publish an entry with references

Try

The Publish an Entry With References request allows you to publish an entry along with all its references at the same time.

Note: At a time, you can publish an entry in up to 50 languages and on 10 environments.

In the “Body” section, you need to specify the following parameters:

  • entries: Pass the details of the main entry i.e., its entry UID, content type UID, the locale code, and the version that you want to publish.
  • locales: Pass the locale codes in which you want to publish your entry and its references. If you do not specify a source locale, the entries will be published in the master locale automatically.
  • environments: Pass the UIDs of the environments to which you want to publish the entries.

Here are some additional parameters that you need to pass in the “Request Body”:

  • "publish_with_reference": true: Pass this parameter to publish an entry along with its references.

    Note: Only one level of referenced entries will be published using this API Request.

  • skip_workflow_stage_check: true: Pass this parameter to skip those entries that do not satisfy the workflow stage of their publishing rule(s) and publish the rest of them.

    Note: Specifically applicable for Workflow enabled organizations, when this parameter is set to “false” and if any one of the entries fails to satisfy the set conditions, NONE of the entries will be sent for publishing.

  • approvals: true: Pass this parameter to publish only those entries that have been approved by the designated approver, and skip the rest that have not yet been approved.

    Note: Specifically applicable for Workflow enabled organizations, when this parameter is set to “false” and if any one of the entries is not approved by the Approver, NONE of the entries will be sent for publishing.

Note: In the Header, you need to use either the stack Management Token (recommended) or the user Authtoken, along with the stack API key, to make valid Content Management API requests. For more information, refer to Authentication.

Unpublish Entry

Unpublish an entry

Try

The Unpublish an entry call will unpublish an entry at once, and also, gives you the provision to unpublish an entry automatically at a later date/time.

In the 'Body' section, you can specify the locales and environments from which you want to unpublish the entry. These details should be specified in the ‘entry’ parameter. However, if you do not specify a locale, it will be unpublished from the master locale automatically.

You also need to mention the master locale and the version number of your entry that you want to publish.

In case of Scheduled Unpublishing, add the scheduled_at key and provide the date/time in the ISO format as its value. Example: "scheduled_at":"2016-10-07T12:34:36.000Z"

Assets

Assets refer to all the media files (images, videos, PDFs, audio files, and so on) uploaded in your Contentstack repository for future use. 

These files can be attached and used in multiple entries. Read more about Assets.

Get All Assets

Get all assets

Try

The Get all assets request returns comprehensive information on all assets available in a stack.

You can add queries to extend the functionality of this API call. Under the URI Parameters section, insert a parameter named query and provide a query in JSON format as the value.

To learn more about the queries, refer to the Queries section of the Content Delivery API doc.

Tip: To include the publish details in the response, make use of the include_publish_details parameter and set its value to ‘true’. This query will return the publish details of the entry in every environment along with the version number that is published in each of the environment.

Get a Single Asset

Get an asset

Try

The Get an asset call returns comprehensive information about a specific version of an asset of a stack.

Tip: To include the publish details in the response, make use of the include_publish_details parameter and set its value to ‘true’. This query will return the publish details of the entry in every environment along with the version number that is published in each of the environment.

Get Assets of a Specific Folder

Get assets of a specific folder

Try

The Get assets of a specific folder retrieves all assets of a specific asset folder; however, it doesn't retrieve the details of subfolders within it.

Get Assets and Subfolders of a Parent Folder

Get assets and subfolders of a parent folder

Try

The Get assets and folders of a parent folder retrieves details of both assets and asset subfolders within a specific parent asset folder.

Upload Asset

Upload asset

Try

The Upload asset call uploads an asset file to your stack.

To upload assets from your local system to Contentstack, you need to use body format as "form-data" and pass the following parameters under it:

ParameterDescription
asset[upload] (mandatory)Select the input type as 'File'. Then, select the asset file that you want to import.
asset[parent_uid] (optional)If needed, assign a parent folder to your asset by passing the UID of the parent folder in this parameter.
asset[title] (optional)Enter a title for your uploaded asset.
asset[description] (optional)Enter a description for your uploaded asset.
asset[tags] (optional)Assign a specific tag to your uploaded asset.

You can try the call manually in any REST API client, such as Postman. Here's a screenshot for reference:

Upload an Asset.png

For easier access, here's the cURL for this API Request:

curl -X POST \
  https://api.contentstack.io/v3/assets \
  -H 'Content-Type: ' \
  -H 'api_key: {api_key_of_your_stack}' \
  -H 'authtoken: {your_authtoken}' \
  -H 'cache-control: no-cache' \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -F 'asset[upload]=@{Filepath e.g., /C:/Users/abc/Desktop/Sample.png}' \
  -F 'asset[parent_uid]={If you need to add this file under an existing asset folder, pass the UID of the parent folder.}' \
  -F 'asset[title]={If needed, enter a title for your uploaded asset.}' \
  -F 'asset[description]={If needed, enter a description for your uploaded asset.}'
  -F 'asset[tags]={If needed, assign a specific tag to your uploaded asset.}'

In the above cURL command, pass the necessary values within the curly brackets. The asset[parent_uid], asset[title], asset[description], and asset[tags] params are optional. You can skip them if not required.

Replace Asset

Replace asset

Try

The Replace asset call will replace an existing asset with another file on the stack.

Tip: You can try the call manually in any REST API client, such as Postman.
Under 'Body', pass a body parameter named asset[upload] and select the input type as 'File'. This will enable you to select the file that you wish to import.
You can assign a parent folder to your asset by using the asset[parent_uid] parameter, where you can pass the UID of the parent folder.
Additionally, you can pass optional parameters such as asset[title] and asset[description] which let you enter a title and a description for the uploaded asset, respectively.

Delete Asset

Delete asset

Try

The Delete asset call will delete an existing asset from the stack.

Rich Text Editor Assets

Get information on RTE assets

Try

The Get information on RTE assets call returns comprehensive information on all assets uploaded through the Rich Text Editor field.

Asset Version Naming

Version naming allows you to assign a name to a version of an asset for easy identification. For more information, refer the documentation.

Set Version Name for Asset

Try

The Set Version Name for Asset request allows you to assign a name to a specific version of an asset.

In the request body, you need to specify the version name to be assigned to the asset version.

Get Details of All Versions of an Asset

Try

The Get Details of All Versions of an Asset request allows you to retrieve the details of all the versions of an asset.

The details returned include the actual version number of the asset; the version name along with details such as the assigned version name, the UID of the user who assigned the name, and the time when the verison was assigned a name; and the count of the versions.

Delete Version Name of Asset

Try

The Delete Version Name of Asset request allows you to delete the name assigned to a specific version of an asset. This request resets the name of the asset version to the version number.

Asset Reference

Get asset references

Try

The Get asset references call returns the details of the entries and the content types in which the specified asset is referenced.

Retrieve Specific Asset Types

Get either only images or videos

Try

The Get either only images or videos call retrieves assets that are either image or video files, based on query request.

You can add queries to extend the functionality of this API call. Under the URI Parameters section, insert a parameter named query and provide a query in JSON format as the value.

To learn more about the queries, refer to the Queries section of the Content Delivery API doc.

Update Asset Details

Update asset revision

Try

The Update asset revision call upgrades a specified version of an asset as the latest version of that asset.

Under 'Body', you need to specify the asset version number that you want to make the latest in raw JSON format, and also provide a "Title" and a "Description" for the asset. Another way to provide a "Title" and a "Description" for the asset is to pass them as optional form-data parameters, i.e., asset[title] and asset[description].

Here's an example of the raw body:

{
    "asset": {
        "title": "Title",
        "description": "Description"
    },
    "version": 3
}
Update asset

Try

The Update asset call updates the title and description of an asset.

Note: This call updates only the meta data of an asset. To replace an asset, try the Replace asset request under Asset Collection.

Under 'Body', you need to pass the updated details of "Title" and "Description" is in the form of 'raw' body as follows:

{
   "asset":{
      "title":"new title",
       "description":"updated description"
     }
}

Another way to provide a "Title" and a "Description" for the asset is to pass them as optional form-data parameters, i.e., asset[title] and asset[description]. You can assign a parent folder to your asset by using the asset[parent_uid] parameter, where you need to pass the UID of the parent folder.

Publish Asset

Publish an asset

Try

The Publish an asset call is used to publish a specific version of an asset on the desired environment either immediately or at a later date/time.

In case of Scheduled Publishing, add the scheduled_at key and provide the date/time in the ISO format as its value. Example: "scheduled_at":"2016-10-07T12:34:36.000Z"

In the 'Body' section, enter the asset details, such as locales and environments, where the assets need to be published. These details should be in JSON format.

Unpublish Asset

Unpublish an asset

Try

The Unpublish an asset call is used to unpublish a specific version of an asset from a desired environment.

In case of Scheduled Unpublishing, add the scheduled_at key and provide the date/time in the ISO format as its value. Example: "scheduled_at":"2016-10-07T12:34:36.000Z"

In the 'Body' section, enter the asset details, such as locales and environments, from where the assets need to be unpublished. These details should be in JSON format.

Asset Folder Collection

Get a single folder

Try

The Get a single folder call gets the comprehensive details of a specific asset folder by means of folder UID.

When executing the API call to search for a subfolder, you need to provide the parent folder UID.

Get a single folder (by name)

Try

The Get a single folder (by name) call retrieves a specific asset folder based on the name provided.

Get subfolders of a parent folder

Try

The Get subfolders of a parent folder request retrieves the details of only the subfolders of a specific asset folder. This request does not retrieve asset files.

Create a folder

Try

The Create a folder call is used to create an asset folder and/or add a parent folder to it (if required).

When executing the API request, provide the parent folder UID.

In the ‘Body’ section, you need to provide a name for the new folder, and if you wish to place this folder within another folder, provide the UID of the parent folder.

Update or move folder

Try

The Update or move folder request can be used either to update the details of a folder or set the parent folder if you want to move a folder under another folder.

When executing the API request, provide the UID of the folder that you want to move/update.

In the ‘Body’ section, you need to provide a new name for your folder, and if you want to move your folder within another folder, then you need provide the UID of the parent folder.

Note: Here are some points that needs to be considered when executing this API request:

  • A maximum of 300 folders can be created.
  • The maximum level of folder nesting is 5.
  • When nesting folder, you cannot nest a folder within the same folder or within its child folders.
Delete a folder

Try

The Delete a folder call is used to delete an asset folder along with all the assets within that folder.

When executing the API call, provide the parent folder UID.

Bulk Operations

You can perform bulk operations such as Publish, Unpublish, and Delete on multiple entries or assets, or Change the Workflow Details of multiple entries or assets at the same time.

Additional Resource: You can also learn how to perform bulk operations on search results.

Points to keep in mind:

  • Each bulk publish API request publishes a maximum of 10 items per request, if the Bulk Publish feature is part of your plan. So, for example, if you publish 100 items, it will make 10 Bulk API requests, and your API count will increment by 10.
  • Mentioning the version number of the entries is optional. If you don't specify the version number, the latest version of the entries will be published or unpublished.
  • Bulk publishing of entries of all locals is not supported. However, you can specify the locales as an array (en-us, fr-fr, zh-zh, and so on) against the ‘locale’ parameter to get them published.

Bulk Publish Operation

Publish entries and assets in bulk

Try

The Publish entries and assets in bulk request allows you to publish multiple entries and assets at the same time.

Note: At a time, you can publish 10 entries in 10 languages and on 10 environments.

In the 'Body' section, you need to specify the locales (mention the locale codes) and environments (mention the names) to which you want to publish the entries or assets. If you do not specify a source locale, the entries or assets will be published in the master locale automatically.

Tip: To schedule the publishing of multiple entries and/or assets, you can make use of the ‘Create a Release’ request. Then, you can deploy this Release and all of the pinned items can be published together either immediately or at a scheduled time to whatever environment you choose.

Within the ‘entries’ parameter, pass these details of each entry – content type UIDs, entry UIDs, locales in which the entries are present, and the version that you want to publish. Within the ‘assets’ parameter, pass these details of each entry – asset UIDs and the version that you want to publish (optional).

If some of the entries added to the bulk publish request do not satisfy the applied publish rules, then all the items will not be published. To publish at least the items that satisfy the publish rules, pass additional query parameters, skip_workflow_stage_check=true and approvals=true.

Let's understand how these two query parameters work while publishing entries.

When you use skip_workflow_stage_check=true as a query parameter, the entries that satisfy the publish rules are sent for publishing, while those entries that have not yet reached the workflow stage defined for the set publish rules will not be sent for publishing. However, if you set this parameter to false and some of the entries included in the bulk publish request have not yet reached the workflow stage defined for the set publish rules, then all the entries selected will not be sent for publishing.

When you use approvals=true as a query parameter, the entries that satisfy the publish rules are sent for publishing, while those entries that have not yet received authorization from the approver assigned to them will not be sent for publishing. However, if you set this parameter to false and some of the entries included in the bulk publish request have not yet received authorization from the approver assigned to them, then all the entries selected will not be sent for publishing.

Note: You need to use either the stack’s Management Token or the user Authtoken (any one is mandatory), along with the stack API key, to make a valid Content Management API request. Read more about authentication.

Bulk Unpublish Operation

Unpublish entries and assets in bulk

Try

The Unpublish entries and assets in bulk request allows you to unpublish multiple entries and assets at the same time.

Note: At a time, you can unpublish 10 entries in 10 languages and on 10 environments.

In the 'Body' section, you need to specify the locales (mention the locale codes) and environments (mention the names) to which you want to unpublish the entries or assets. If you do not specify a source locale, the entries or assets will be unpublished in the master locale automatically.

Tip: To schedule the unpublishing of multiple entries and/or assets, you can make use of the ‘Create a Release’ request. Then, you can deploy this Release and all of the pinned items can be unpublished together either immediately or at a scheduled time to whatever environment you choose.

Within the ‘entries’ parameter, pass these details of each entry – content type UIDs, entry UIDs, locales in which the entries are present, and the version that you want to unpublish. Within the ‘assets’ parameter, pass these details of each entry – asset UIDs and the version that you want to unpublish (optional).

If some of the entries added to the bulk unpublish request do not satisfy the applied publish rules, then all the items will not be unpublished. To unpublish at least the items that satisfy the publish rules, pass additional query parameters, skip_workflow_stage_check=true and approvals=true.

Let's understand how these two query parameters work while unpublishing entries.

When you use skip_workflow_stage_check=true as a query parameter, the entries that satisfy the publish rules are sent for unpublishing, while those entries that have not yet reached the workflow stage defined for the set publish rules will not be sent for unpublishing. However, if you set this parameter to false and some of the entries included in the bulk unpublish request have not yet reached the workflow stage defined for the set publish rules, then all the entries selected will not be sent for unpublishing.

When you use approvals=true as a query parameter, the entries that satisfy the publish rules are sent for unpublishing, while those entries that have not yet received authorization from the approver assigned to them will not be sent for unpublishing. However, if you set this parameter to false and some of the entries included in the bulk unpublish request have not yet received authorization from the approver assigned to them, then all the entries selected will not be sent for unpublishing.

Note: You need to use either the stack’s Management Token or the user Authtoken (any one is mandatory), along with the stack API key, to make a valid Content Management API request. Read more about authentication.

Bulk Delete Operation

Delete entries and assets in bulk

Try

The Delete entries and assets in bulk request allows you to delete multiple entries and assets at the same time.

Note: At a time, you can delete 10 entries in a bulk delete request.

In the 'Body' section, you need to specify the content type UIDs, entry UIDs or asset UIDs, and locales of which the entries or assets you want to delete.

Note: You need to use either the stack’s Management Token or the user Authtoken (any one is mandatory), along with the stack API key, to make a valid Content Management API request. Read more about authentication.

Bulk Update Workflow Details Operation

The ‘Change Workflow Details’ action is a new option that allows you to change workflow details (such as stage, assignee, due date, and comments) of multiple entries at the same time. Read more about how this option works.

Update workflow details in bulk

Try

The Update workflow details in bulk request allows you to update the workflow details for multiple entries at the same time.

Note: You can change the workflow stage of multiple entries only if all the entries have been assigned the same workflow stage and are associated with the same workflow.

In the 'Body' section, you need to provide the details of the workflow stage. Enter a comment for the assigned user, if needed; provide the due date; set notification settings to ‘true’, so that the specified user will be notified of it; enter the UID of the workflow stage; and finally, enter the user details, such as UID, name, and email address of the user.

Note: At a time, you can update the workflow details for 10 entries in a bulk update workflow details request.

Within the ‘entries’ parameter, pass these details of each entry – content type UIDs, entry UIDs, and locales in which the entries are present.

Note: You need to use either the stack’s Management Token or the user Authtoken (any one is mandatory), along with the stack API key, to make a valid Content Management API request. Read more about authentication.

Extensions

Extensions let you create custom fields and custom widgets that lets you customize Contentstack's default UI and behavior. Read more about Extensions.

Custom Fields

This type of extension lets you create custom fields that you can use in your content types. Read more.

Get all custom fields

Try

The Get all custom fields request is used to get the information of all custom fields created in a stack.

Get a single custom field

Try

The Get a single custom field request gets the comprehensive details of a specific custom field.

Upload a custom field

Try

The Upload a custom field request is used to upload a custom field to Contentstack.

In the ‘Body’ section, you need to provide the following ‘Body’ parameters under ‘form-data’:

  • extension[upload]: Select the HTML file of the custom field that you want to upload
  • extension[title]: Enter the title of the custom field that you want to upload
  • extension[data_type]: Enter the data type for the input field of the custom field
  • extension[tags]: Enter the tags that you want to assign to the custom field
  • extension[multiple]: Enter ‘true’ if you want your custom field to store multiple values
  • extension[type]: Enter type as ‘field’, since this is a custom field extension.

Tip: You can try the call manually in any REST API client, such as Postman. Under 'Body', for the extension[upload] parameter, select the input type as 'File'. This will enable you to select the file that you wish to import.

Create a custom field with source URL

Try

The Create a custom field with source URL call is used to create a custom field that is hosted externally.

In the ‘Body’ section, you need to provide details of the custom field, such as its tags, data type, title, external source link, set if the field is to take multiple values or not, and configuration details.

Create a custom field with source code

Try

The Create a custom field with source code request is used to create a custom field in Contentstack by providing the source code of the extensions. This source code will be hosted on Contentstack.

In the ‘Body’ section, you need to provide details of the custom field, such as its tags, data type, title, source code of the extension, set if the field is to take multiple values or not, and configuration details.

Update a custom field

Try

The Update a custom field request is used to update the details of a custom field.

In the ‘Body’ section, you need to provide details of the custom field, such as its tags, data type, title, external source link (or the updated external source code), set if the field is to take multiple values or not, and configuration details.

Delete custom field

Try

The Delete custom field request is used to delete a specific custom field.

Create Content Type with Extension Field

Try

The Create Content Type with Extension Field request is used to create a content type that includes a custom field.

Custom Widgets

This type of extensions lets you add widgets that help you analyze content of an entry and recommend content ideas. Read more.

Get all widgets

Try

The Get widgets request is used to get the information of all custom widgets created in a stack.

Get widgets of a content type

Try

The Get widgets of a content type request gets the comprehensive details of all widgets that are assigned to a specific content type.

Upload a widget

Try

The Upload a widget request is used to upload a new custom widget to a stack.

In the ‘Body’ section, you need to provide the following ‘Body’ parameters under ‘form-data’:

  • extension[upload]: Select the HTML file of the widget that you want to upload
  • extension[title]: Enter the title of the widget that you want to upload
  • extension[tags]: Enter the tags that you want to assign to the widget
  • extension[scope]: Enter either {"content_types":["$all"]} or {"content_types":["content_type_uid1”, “content_type_uid2”, “..."]} to apply this widget to all content types or specific content types, respectively
  • extension[type]: Enter type as ‘widget’, since this is a custom widget extension

Tip: You can try the call manually in any REST API client, such as Postman. Under 'Body', for the extension[upload] parameter, select the input type as 'File'. This will enable you to select the file that you wish to import.

Create widget with source URL

Try

The Create Widget with source URL call is used to create a widget that is hosted externally.

In the ‘Body’ section, you need to provide details of the widget, such as its tags, title, external source link (src), configuration details, set if the extension is a widget or field, and specify the scope, i.e., the content types to which you want to apply the widget.

Create widget with source code

Try

The Create widget with source code request is used to create a widget in Contentstack by providing the source code. This source code will be hosted on Contentstack.

In the ‘Body’ section, you need to provide details of the widget, such as its tags, title, source code of the widget, configuration details, set if the extension is a widget or field, and specify the scope i.e., the content types that you want to apply the widget.

Update a widget

Try

The Update a widget request is used to update the details of a widget.

In the ‘Body’ section, you need to provide details of the widget, such as its tags, title, external source link (or the updated external source code), configuration details, set if the extension is a widget or field, and specify the scope i.e., the content types that you want to apply the widget.

Delete a widget

Try

The Delete a widget call is used to delete a specific custom widget.

Dashboard Widgets

This type of extension lets you create widgets for your dashboard. Read more.

Get All Dashboard Widgets

Try

The Get All Dashboard Widgets request is used to get the information of all the enabled custom dashboard extension.

Upload Dashboard Widget

Try

The Upload Dashboard Widget request uploads the widget to the Stack Dashboard.

In the ‘Body’ section, you need to provide the following ‘Body’ parameters under ‘form-data’:

  • extension[upload]: Select the HTML file of the widget that you want to upload.
  • extension[title]: Enter the title of the widget that you want to upload.
  • extension[tags]: Enter the tags that you want to assign to the widget.
  • extension[type]: Enter type as ‘dashboard’, since this is a custom widget extension.
Create a Dashboard Widget with Source URL

Try

The Create a Dashboard Widget with Source URL request is used to upload an extension hosted externally.

In the ‘Body’ section, you need to provide details of the dashboard widget, such as its tags, title, external source link (src), configuration details, and set if the extension is a widget or field.

Create a Dashboard Widget with Source code

Try

The Create dashboard widget with source code request is used to create a widget in Contentstack by providing the source code. This source code will be hosted on Contentstack.

In the ‘Body’ section, you need to provide details of the widget, such as its tags, title, source code of the widget, configuration details, and set if the extension is a widget or field.

Update the Dashboard Widget

Try

The Update dashboard widget request is used to update the details of an widget.

In the ‘Body’ section, you need to provide details of the extension, such as its tags, data type, title, and configuration details.

Delete the Dashboard Widget

Try

The ‘Delete a dashboard widget’ call is used to delete a specific custom dashboard.

Releases

You can pin a set of entries and assets (along with the deploy action, i.e., publish/unpublish) to a ‘release’, and then deploy this release to an environment. This will publish/unpublish all the the items of the release to the specified environment. Read more about Releases.

Releases Collection

Get all Releases

Try

The Get all Releases request retrieves a list of all Releases of a stack along with details of each Release.

Get a single Release

Try

The Get a single Release request gets the details of a specific Release in a stack.

When executing the API request, provide the Release UID as parameter.

Create a Release

Try

The Create a Release request allows you to create a new Release in your stack. To add entries/assets to a Release, you need to provide the UIDs of the entries/assets in ‘items’ in the request body.

Update a Release

Try

The Update a Release call allows you to update the details of a Release, i.e., the ‘name’ and ‘description’.

When executing this API request, provide the Release UID as parameter. In the 'Body' section, you need to provide the new name and description of the Release that you want to update.

Delete a Release

Try

The Delete a Release request allows you to delete a specific Release from a stack.

When executing the API request, provide the Release UID.

Release Items

Get all items in a Release

Try

The Get all items in a Release request retrieves a list of all items (entries and assets) that are part of a specific Release.

When executing the API request, you need to provide the Release UID.

Add a single item to a Release

Try

The Add a single item to a Release request allows you to add an item (entry or asset) to a Release.

When executing the API request, you need to provide the Release UID. In the 'Body' section, you need to provide the details of the item such as the UID, version (of the entry), content type UID (of an entry), the action to be performed (publish/unpublish), and the locale of the item.

Add multiple items to a Release

Try

The Add multiple items to a Release request allows you to add multiple items (entries and/or assets) to a Release.

When executing the API request, you need to provide the Release UID. In the 'Body' section, you need to provide the details of the items such as their UIDs, versions (in case of entries), content type UIDs (in case of entries), the action to be performed (publish/unpublish), and the locales of the items.

Note: In a single request, you can add maximum 25 items (entries/assets) to a Release.

Remove an item from a Release

Try

The Remove an item from a Release request removes one or more items (entries and/or assets) from a specific Release.

When executing the API request, provide the Release UID. In the 'Body' section, you need to provide the details of the item such as their UIDs, version (of the entry), content type UID (of an entry), the action to be performed (publish/unpublish), and the locale of the item.

Delete multiple items from a Release

Try

The Delete multiple items from a Release request deletes one or more items (entries and/or assets) from a specific Release.

When executing the API request, provide the Release UID. In the 'Body' section, you need to provide the UIDs of the items along with details such as their locale, versions, the action to be performed on the items (publish/unpublish), and content type UID of entries (if any).

Deploy/Execute a Release

Deploy a Release

Try

The Deploy a Release request deploys a specific Release to specific environment(s) and locale(s).

When executing the API request, provide the Release UID. In the 'Body' section, you need to provide the details of the Release that you want to deploy. For example, you need to provide the action, environment(s), and the locale(s) on which the Release should be deployed.

Clone a Release

Clone a Release

Try

The Clone a Release request allows you to clone (make a copy of) a specific Release in a stack.

When executing the API request, provide the Release UID. In the 'Body' section, you need to provide the new name and description of the cloned Release.

Workflows

Workflow is a tool that allows you to streamline the process of content creation and publishing, and lets you manage the content lifecycle of your project smoothly.

Get All Workflows

Get all workflows

Try

The Get all Workflows request retrieves the details of all the Workflows of a stack.

Get a Single Workflow

Get a single workflow

Try

The Get a Single Workflow request retrieves the comprehensive details of a specific Workflow of a stack.

Create a Workflow

Create a workflow

Try

The Create a Workflow request allows you to create a Workflow.

In the 'Body' section, you can provide the details of the workflow that includes name, content types, owners, description, and workflow stages of your Workflow.

To control who can edit an entry at different stages of the workflow, you can pass the entry_lock parameter inside each workflow stage.

Note: Workflow superusers, organization owners, and stack owners/admins can edit or delete the entry in any workflow stage, irrespective of the stage access rules set for that stage.

You can assign any one of the following values to this parameter:

  • $none: This is the default value for all workflow stages. This value allows all users to have edit access over the entry at any workflow stage until the value for the entry_lock parameter is changed.
  • $others: Set the entry_lock parameter to $others to allow only those users who have stage transition rights to edit the entry in the current workflow stage.
  • $all: Set the entry_lock parameter to $all to restrict all users from accessing the entry.

    Note: Users with stage transition rights, however, will still be able to change the workflow stage of the entry.

Note: The entry is available for editing, by default, in the first stage that you create in your workflow. As a result, the entry_lock parameter is set to $none for the first stage in the workflow.

Add or Update Workflow Details

Add or update workflow details

Try

The Add or Update Workflow request allows you to add a workflow stage or update the details of the existing stages of a workflow.

In the 'Body' section, you can provide the updated details of the name, content types, owners, description, and workflow stages of your Workflow.

To control who can edit an entry at different stages of the workflow, you can pass the entry_lock parameter inside each workflow stage.

Note: Workflow superusers, organization owners, and stack owners/admins can edit or delete the entry in any workflow stage, irrespective of the stage access rules set for that stage.

You can assign any one of the following values to this parameter:

  • $none: This is the default value for all workflow stages. This value allows all users to have edit access over the entry at any workflow stage until the value for the entry_lock parameter is changed.
  • $others: Set the entry_lock parameter to $others to allow only those users who have stage transition rights to edit the entry in the current workflow stage.
  • $all: Set the entry_lock parameter to $all to restrict all users from accessing the entry.

    Note: Users with stage transition rights, however, will still be able to change the workflow stage of the entry.

Note: The entry is available for editing, by default, in the first stage that you create in your workflow. As a result, the entry_lock parameter is set to $none for the first stage in the workflow.

Disable Workflow

Disable workflow

Try

The Disable Workflow request allows you to disable a workflow.

Enable Workflow

Enable workflow

Try

The Enable Workflow request allows you to enable a workflow.

Delete Workflow

Delete workflow

Try

The Delete Workflow request allows you to delete a workflow.

Entry Workflow Stages

Set entry workflow stage

Try

The Set Entry Workflow Stage request allows you to either set a particular workflow stage of an entry or update the workflow stage details of an entry.

In the 'Body' section, you need to provide the details of the workflow stage. Enter a comment for the assigned user, if needed; provide the due date; set notification settings to ‘true’, so that the specified user will be notified of it; enter the UID of the workflow stage; and finally, enter the user details, such as UID, name, and email address of the user.

Publish Rules Collection

Create publish rules

Try

The Create Publish Rules request allows you to create publish rules for the workflow of a stack.

Update publish rules

Try

The Add or Update Publish Rules request allows you to add a publish rule or update the details of the existing publish rules of a workflow.

Delete publish rules

Try

The Delete Publish Rules request allows you to delete an existing publish rule. 

Get all publish rules

Try

The Get all Publish Rules request retrieves the details of all the Publish rules of a workflow. 

Get a single publish rule

Try

The Get a Single Publish Rule request retrieves the comprehensive details of a specific publish rule of a Workflow.

Publish Rules by Content Types

Get publish rules by content types

Try

The Get Publish Rules by Content Types request allows you to retrieve details of a Publish Rule applied to a specific content type of your stack.

When executing the API request, in the 'Header' section, you need to provide the API Key of your stack and the authtoken that you receive after logging into your account.

Publish Request Approval

Request/Accept/Reject Entry Publish Request

Try

This multipurpose request allows you to either send a publish request or accept/reject a received publish request.

When executing the API request, in the 'Header' section, you need to provide the API Key of your stack and the authtoken that you receive after logging into your account.

In the 'Body' section, you need to provide the details of the publish rule, such as its UID, action (‘publish’, ‘unpublish’, or ’both’), status (this could be ‘0’ for Approval Requested, ‘1’ for ‘Approval Accepted’, and ‘-1’ for ‘Approval Rejected’), notification setting, and comment for the approver.

Workflow Tasks

Get all Tasks

Try

The Get all Tasks request retrieves a list of all tasks assigned to you.

When executing the API request, in the 'Header' section, you need to provide the API Key of your stack and the authtoken that you receive after logging into your account.

Labels

Labels allow you to group a collection of content within a stack. Using labels you can group content types that need to work together. Read more about Labels.

Labels Collection

Get all labels

Try

This call fetches all the existing labels of the stack.

When executing the API call, under the 'Header' section, you need to enter the API key of your stack and the authtoken that you receive after logging into your account.

You can add queries to extend the functionality of this API call. Under the URI Parameters section, insert a parameter named query and provide a query in JSON format as the value.

To learn more about the queries, refer to the Queries section of the Content Delivery API doc.

Get a single label

Try

The Get label call returns information about a particular label of a stack.

When executing the API call, under the 'Header' section, you need to enter the authtoken that you receive after logging into your account.

Add label

Try

This call is used to create a label.

When executing the API call, under the 'Header' section, you need to enter the API key of your stack and the authtoken that you receive after logging into your account.

In the 'Body' section, enter the label details, such as the name of the label, the uid of the parent label, and the content types that need to be included in the label. These details need to be provided in JSON format.

Update label

Try

The Update label call is used to update an existing label.

When executing the API call, under the 'Header' section, you need to enter the authtoken that you receive after logging into your account.

In the 'Body' section, enter the updated details of your label, which include the name of the label, the uid of the parent label, and the content types that need to be included in the label. These details need to be provided in JSON format.

Delete label

Try

The Delete label call is used to delete a specific label.

When executing the API call, under the 'Header' section, you need to enter the authtoken that you receive after logging into your account.

Languages

Contentstack has a sophisticated multilingual capability. It allows you to create and publish entries in any language. This feature allows you to set up multilingual websites and cater to a wide variety of audience by serving content in their local language(s).

Read more about Languages.

Language Collection

Get all languages

Try

This call fetches the list of all languages (along with the language codes) available for a stack.

When executing the API call, under the 'Header' section, you need to enter the authtoken that you receive after logging into your account.

You can add queries to extend the functionality of this API call. Under the URI Parameters section, insert a parameter named query and provide a query in JSON format as the value.

To learn more about the queries, refer to the Queries section of the Content Delivery API doc.

Add a language

Try

This call lets you add a new language to your stack.

When executing the API call, under the 'Header' section, you need to enter the API key of your stack and the authtoken that you receive after logging into your account.

In the 'Body' section, enter the language codes in JSON format.

Get a language

Try

The Get a language call returns information about a specific language available on the stack.

When executing the API call, under the 'Header' section, you need to enter the authtoken that you receive after logging into your account.

Update language

Try

The Update language call will let you update the details (such as display name) of an existing language of your stack.

When executing the API call, under the 'Header' section, you need to enter the authtoken that you receive after logging into your account.

In the 'Body' section, enter the updated details of your language in JSON format, for example you can update the display name of the language.

Delete language

Try

The Delete language call deletes an existing language from your stack.

When executing the API call, under the 'Header' section, you need to enter the API key of your stack and the authtoken that you receive after logging into your account.

Fallback Languages

Language fallback allows entries created in a particular language to initially inherit data from the fallback language instead of directly inheriting content from the master language. For more information, refer the documentation for Fallback Language.

Set a fallback language

Try

The ‘Set a fallback language’ request allows you to assign a fallback language for an entry in a particular language.

When executing the API call, under the 'Header' section, you need to enter the API key of your stack and the authtoken that you receive after logging in to your account.

In the 'Body' section, enter the language codes in JSON format.

Note: The language set as a fallback language will always inherit data from the master language if it does not have localized content.

Update fallback language

Try

The ‘Update fallback language’ request allows you to update the fallback language for an existing language of your stack.

When executing the API call, under the 'Header' section, you need to enter the API key of your stack and the authtoken that you receive after logging in to your account.

In the 'Body' section, enter the updated details of the fallback language in JSON format.

Note: The language set as a fallback language will always inherit data from the master language if it does not have localized content.

Environment

A publishing environment corresponds to one or more deployment servers or a content delivery destination where the entries need to be published.

Read more about Environments.

Environment Collection

Get all environments

Try

The Get all environments call fetches the list of all environments available in a stack.

You can add queries to extend the functionality of this API call. Under the URI Parameters section, insert a parameter named query and provide a query in JSON format as the value.

To learn more about the queries, refer to the Queries section of the Content Delivery API doc.

Get a single environment

Try

The Get a single environment call returns more details about the specified environment of a stack.

When executing the API call, under the 'Header' section, you need to enter the authtoken that you receive after logging into your account.

Add an environment

Try

The Add an environment call will add a publishing environment for a stack.

When executing the API call, under the 'Header' section, you need to enter the API key of your stack and the authtoken that you receive after logging into your account.

In the 'Body' section, mention the environment name, server names that are part of the environment, the urls (which include the language code and the URL of the server), and the option to deploy content to a server.

Update environment

Try

The Update environment call will update the details of an existing publishing environment for a stack.

When executing the API call, under the 'Header' section, you need to enter the API key of your stack and the authtoken that you receive after logging into your account.

In the 'Body' section, enter the updated details of the environment. You can modify the environment name, server names that are part of the environment, the urls (which include the language code and the URL of the server), and the option to deploy content to a server.

Delete environment

Try

The Delete environment call will delete an existing publishing environment from your stack.

When executing the API call, under the 'Header' section, you need to enter the API key of your stack and the authtoken that you receive after logging into your account.

Tokens

Delivery Tokens provide read-only access to the associated environments. Used along with the stack API key, it is used to make authorized Content Delivery API requests for retrieving the published content of an environment.

Read more about Delivery Tokens.

Delivery Token Collection

Get all delivery tokens

Try

The Get all delivery tokens request returns the details of all the delivery tokens created in a stack.

Get a single delivery token

Try

The Get a single delivery token request returns the details of all the delivery tokens created in a stack.

Create delivery token

Try

The Create delivery token request is used to create a delivery token in the stack.

In the Request Body, you need to pass the details of the delivery token in JSON format. The details include the name, description, and the environment of the delivery token.

Note: It is highly recommended to set only one publishing environment per delivery token.

Update delivery token

Try

The Update delivery token request lets you update the details of a delivery token.

In the Request Body, you need to pass the updated details of the delivery token in JSON format. The details include the updated name, description, and/or the environment of the delivery token.

Delete delivery token

Try

The Delete delivery token request deletes a specific delivery token.

Roles

A role is a collection of permissions that will be applicable to all the users who are assigned this role.

Read more about Roles.

Role Collection

Get all roles

Try

The ‘Get all roles’ request returns comprehensive information about all roles created in a stack.

You can add queries to extend the functionality of this API request. Under the URI Parameters section, insert a parameter named query and provide a query in JSON format as the value.

To learn more about the queries, refer to the Queries section of the Content Delivery API doc.

Get a single role

Try

The Get a single role request returns comprehensive information on a specific role.

Create a role

Try

The Create a role call creates a new role in a stack.

In the 'Body' section, mention the role name, description, users, additional roles, rules  (includes the actions that can be performed on entries, fields, and/or assets), and permissions (which include the details of the content types, environments, and languages that are accessible).

Update role

Try

The Update role call lets you modify an existing role of your stack. However, the pre-existing system roles cannot be modified.

In the 'Body' section, include the updated details of the role which include name, description, users, additional roles, rules (includes the actions that can be performed on entries, fields, and/or assets), and permissions (which include the details of the content types, environments, and languages that are accessible).

Delete role

Try

The Delete role call deletes an existing role from your stack.

Webhooks

A webhook is a mechanism that sends real-time information to any third-party app or service to keep your application in sync with your Contentstack account. Webhooks allow you to specify a URL to which you would like Contentstack to post data when an event happens. Read more about Webhooks.

Webhook Collection

Get all webhooks

Try

This call returns comprehensive information on all the available webhooks in the specified stack.

Tip: Execute this call when you wish to retrieve the uid of a webhook.

When executing the API call, under the 'Header' section, you need to enter the authtoken that you receive after logging into your account.

Get webhook

Try

The Get a webhookcall returns comprehensive information on a specific webhook.

When executing the API call, under the 'Header' section, you need to enter the authtoken that you receive after logging into your account.

Create a webhook

Try

The Create a webhook request allows you to create a new webhook in a specific stack.

In the “Body” section, you need to enter the name of the webhook; the destination details i.e., target urls, basic authentication details, and custom headers; and the channels; and set the retry_policy and the disabled parameters as per requirement.

The retry_policy parameter by default is set to automatic and enables the webhook auto-retry option, however, you can change the key value to manual. The disabled parameter, on the other hand, allows you to enable or disable the webhook. You can set its value to either false to enable the webhook and true to disable the webhook.

Note: In the Header, you need to use either the stack Management Token (recommended) or the user Authtoken, along with the stack API key, to make valid Content Management API requests. For more information, refer to Authentication.

Update webhook

Try

The Update webhook request allows you to update the details of an existing webhook in the stack.

In the “Body” section, you need to enter new details such as the name of the webhook; the destination details i.e., target urls, basic authentication details, and custom headers; and the channels; or reset the retry_policy or disabled parameters as per requirement.

The retry_policy parameter by default is set to automatic and enables the webhook auto-retry option, however, you can change the key value to manual. The disabled parameter, on the other hand, allows you to enable or disable the webhook. You can set its value to either false to enable the webhook and true to disable the webhook.

Note: In the Header, you need to use either the stack Management Token (recommended) or the user Authtoken, along with the stack API key, to make valid Content Management API requests. For more information, refer to Authentication.

Delete webhook

Try

The Delete webhook call deletes an existing webhook from a stack.

When executing the API call, under the 'Header' section, you need to enter the API key of your stack and the authtoken that you receive after logging into your account.

Export Webhook

Export a Webhook

Try

The Export a Webhook request exports an existing webhook. The exported webhook data is saved in a downloadable JSON file.

Import Webhook

The 'Import Webhook' section consists of the following two requests that will help you to import new Webhooks or update existing ones by uploading JSON files.

Note: You can try the call manually in any REST API client, such as Postman, by passing a 'Body' parameter named webhook under form-data. Select the input type as 'File' and select the JSON file of the webhook that you want to import.

Import a Webhook

Try

The Import Webhook request imports a webhook. To import a webhook, you need to upload a JSON file with the webhook data.

Import an Existing Webhook

Try

The Import an Existing Webhook request will allow you to update the details of an existing webhook.

Get Webhook Executions

Get executions of a webhook

Try

The Get executions of a webhook call will provide the execution details of a specific webhook, which includes the execution UID. This detail is instrumental in retrieving webhook logs and retrying a failed webhook. Each execution of a webhook is assigned a unique UID that allows you to gather information, such as request-response body, retry attempts, and so on, pertaining to a specific execution of the webhook.

This API request will return a maximum of 100 records while fetching the execution details for a specific webhook. Previously, there was no limit on the number of records returned. You can use the "skip" parameter to fetch older records.

Webhook Retry

Retry a webhook

Try

This call makes a manual attempt to execute a webhook after the webhook has finished executing its automatic attempts.

When executing the API call, in the 'URI Parameter' section, enter the execution UID that you receive when you execute the 'Get executions of webhooks' call.

Get Execution Log

Get latest execution log of a webhook

Try

This call will return a comprehensive detail of all the webhooks that were executed at a particular execution cycle.

When executing the API call, in the 'URI Parameter' section, enter the execution UID that you receive when you execute the 'Get executions of webhooks' call.

Audit Log

Audit log displays a record of all the activities performed in a stack and helps you keep a track of all published items, updates, deletes, and current status of the existing content.

Read more about Audit Log.

Get Audit Log

Get audit log

Try

The Get audit log request is used to retrieve the audit log of a stack.

You can apply queries to filter the results. Refer to the Queries section for more details.

Get Audit Log Item

Get audit log item

Try

The Get audit log item request is used to retrieve a specific item from the audit log of a stack.

Publish Queue

The Publish Queue displays the historical and current details of activities such as publish, unpublish, or delete that can be performed on entries and/or assets. It also shows details of Release deployments. These details include time, entry, content type, version, language, user, environment, and status.

For more details, refer the Publish Queue documentation.

Get Publish Queue

Get publish queue

Try

The Get publish queue request returns comprehensive information on activities such as publish, unpublish, and delete that have performed on entries and/or assets. This request also includes the details of the release deployments in the response body.

Note: You can retrieve the publish queue details for activities performed on entries and/or assets of your stack in the last 30 days.

You can apply queries to filter the results. Refer to the Queries section for more details.

Note: In the Header, you need to pass either the stack’s Management Token (highly recommended) or the user Authtoken, along with the stack API key, to make valid Content Management API requests. For more information, refer to Authentication.

Get Publish Queue Activity

Get publish queue activity

Try

The Get publish queue activity request returns comprehensive information on a specific publish, unpublish, or delete action that was performed on an entry and/or asset. You can also retrieve details of a specific release deployment.

Note: You can retrieve the publish queue details for activities performed in the last 30 days only.

You can apply queries to filter the results. Refer to the Queries section for more details.

Note: In the Header, you need to pass either the stack’s Management Token (highly recommended) or the user Authtoken, along with the stack API key, to make valid Content Management API requests. For more information, refer to Authentication.

Cancel Scheduled Action

Cancel scheduled action

Try

The Cancel Scheduled Action request will allow you to cancel any scheduled publishing or unpublishing activity of entries and/or assets and also cancel the deployment of releases.

top-arrow