Automate Management API
Introduction
Base URL
- AWS North America (AWS NA): https://automations-api.contentstack.com/
- AWS Europe (AWS EU): https://eu-prod-automations-api.contentstack.com
- AWS Australia (AWS AU): https://au-prod-automations-api.contentstack.com
- Azure North America (Azure NA): https://azure-na-automations-api.contentstack.com
- Azure Europe (Azure EU): https://azure-eu-automations-api.contentstack.com
- GCP North America (GCP NA): https://gcp-na-automations-api.contentstack.com
- GCP Europe (GCP EU): https://gcp-eu-automations-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 Automate Management API.
The Automate Management API is used to manage your projects and automations present in an organization. This includes creation, updation, deletion, and fetching requests.
To use the Automate Management API, you need to authenticate yourself with an Authtoken. Read more about it in Authentication.
Note: The initial release of the Automate Management API currently does not include support for Management token for authentication. However, this feature is scheduled to be introduced in upcoming releases.
Authentication
Contentstack provides token-based authentication that allows you to create, update, delete, and fetch the content of your Contentstack account. You can use the user Authtoken, to make Automate Management API requests.
Authtokens are user-specific tokens generated when a user logs into Contentstack. Read more about the different types of tokens.
For API Key and Authtoken-based authentication
- Pass the user Authtoken against the authtoken parameter as header.
- Pass the Organization ID against the organization_uid parameter as header.
How to Get Authtoken
To retrieve the authtoken, log into your Contentstack account by using the “Log into 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 into your account” request multiple times. These tokens do not have an expiration limit. However, currently, there is a maximum limit of 20 valid tokens that a user can use per account at a time to execute the CMA requests.
Note: If you already have valid 20 tokens, creating a new authtoken will automatically expire the oldest authtoken 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 a user authtoken will not work. The owner and users of the organization who have permission to access the organization without SSO can use the Content Management APIs. Learn more about REST API Usage.
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 Automate Management API enforces the following rate limits:
- Read (GET) and 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.
The aforementioned limits are configurable depending on your plan. For more information, contact our Support team.
API Conventions
- The base URL for Automate Management API for different regions can be found in the Base URL section.
- The API version can be found in the URL, e.g. automations-api.contentstack.com/v1/endpoint.
- Automate 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, Automate returns an error.
Automate 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 Automate'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. |
Note: The error codes that we get in the JSON response are not HTTP error codes but are custom Automate error codes that are used for internal purposes.
Using Postman Collection
Contentstack offers you a Postman Collection that helps you try out our Automate Management API. You can download this collection, connect to your Contentstack account, and try out the Automate Management API with ease.
Learn more about how to get started with using the Postman Collection for Automate Management API.
API References
Projects
Get All Projects
The Get all projects request returns comprehensive information of all the projects related to the Organization in which they are created.
To configure the permissions for your application via OAuth, include the automationhub.projects.management:read scope.
Note: If you do not specify a value for the optional “limit” query parameter, the API request will by default return the initial 100 items.
Get a Single Project
The Get a single project request fetches a specific project created in your organization. When executing the API request, you need to provide the organization UID and your authtoken in the Request Header.
To configure the permissions for your application via OAuth, include the automationhub.projects.management:read scope.
Create a Project
The Create a project request lets you create a project in your organization.
To configure the permissions for your application via OAuth, include the automationhub.projects.management:writescope.
Update a Project
The Update a project request lets you update certain details such as the description, tags, and title of an existing project in an Organization.
To configure the permissions for your application via OAuth, include the automationhub.projects.management:write scope.
Here’s an example of the Request body:
{
"description": "New Description",
"tags": ["tag1", "tag2",...],
"title": "New Title"
}Delete a Project
The Delete a project request lets you delete an existing project in an organization.
Automations
Get All Automations
The Get all automations request returns comprehensive information of all the automations created in a project.
To configure the permissions for your application via OAuth, include the automationhub.automations:read scope.
To get a list of automations that are active, you need to pass the query={'active':'true'} parameter.
Note: If you do not specify a value for the optional “limit” query parameter, the API request will by default return the initial 100 items.
Get a Single Automation
The Get a single automation request fetches a specific automation from a project in which it was created.
To configure the permissions for your application via OAuth, include the automationhub.automations:read scope.
Activate/Deactivate an Automation
The Activate/Deactivate an automation request sets an automation to an active or inactive state.
To configure the permissions for your application via OAuth, include the automationhub.automations:write scope.
Note: To activate/deactivate an automation, you must have a trigger and an action configured in your project.
Execution Logs
Get Execution Log
The Get execution log request is used to retrieve the execution log of a project.
To configure the permissions for your application via OAuth, include the automationhub.executions:read scope.
Note: If you do not specify a value for the optional “limit” query parameter, the API request will by default return the initial 100 items.
Get an Execution Log Item
The Get an execution log item request is used to retrieve a specific item from the execution log of a project.
To configure the permissions for your application via OAuth, include the automationhub.executions:read scope.
Audit Logs
Get Audit Log
The Get audit log request returns the audit log of a specific project.
To configure the permissions for your application via OAuth, include the automationhub.audit-log:read scope.
Note: If you do not specify a value for the optional “limit” query parameter, the API request will by default return the initial 30 items.
Get an Audit Log Item
The Get an audit log item request is used to retrieve a specific item from the audit log of a project.
To configure the permissions for your application via OAuth, include the automationhub.audit-logs:read scope.
Project Variables
Get All Project Variables
The Get all project variables request returns comprehensive information of all the project variables defined in a project.
To configure the permissions for your application via OAuth, include the automationhub.variables:read scope.
Note: If you do not specify a value for the optional “limit” query parameter, the API request will by default return the initial 100 items.
Get a Single Project Variable
The Get a single project variable request fetches a specific project variable defined in a project.
To configure the permissions for your application via OAuth, include the automationhub.variables:read scope.
Create a Project Variable
The Create a project variable request lets you create a project variable in a project.
To configure the permissions for your application via OAuth, include the automationhub.variables:write scope.
Update a Project Variable
The Update a project variable request lets you update the key, value and type of a project variable.
To configure the permissions for your application via OAuth, include the automationhub.variables:write scope.
Delete a Project Variable
The Delete a project variable request lets you delete a specific project variable from a project.
To configure the permissions for your application via OAuth, include the automationhub.variables:write scope.
Accounts
Get All Accounts
The Get all accounts request returns comprehensive information of all the accounts in a project.
To configure the permissions for your application via OAuth, include the automationhub.accounts:read scope.
Note: If you do not specify a value for the optional “limit” query parameter, the API request will by default return the initial 100 items.
Get a Single Account
The Get a single account request fetches a specific account in a project.
To configure the permissions for your application via OAuth, include the automationhub.accounts:read scope.
Postman Collection
About Automate Postman Collection
The Automate 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 Automate Postman collection you will need to have the Postman. You can either download the Desktop app or use Postman for Web.
Note: If you have already installed Postman for your device, go to the Download Latest Postman Collection for Automate section.
Postman is available for Windows (x32), Windows (x64), Mac (Intel Chip / Apple Chip), and Linux environments.
Download Latest Collection
Once you have installed Postman on your device, click the Run in Postman button to start working with the Automate Management API endpoints for Contentstack.
Note: The Automate Postman collection does not support the now deprecated Postman Chrome extension. Make sure you have installed the latest version of the Postman desktop app.
This opens the Fork collection into your workspace modal from where you can proceed to download/work with the Automate Postman collection in the following three ways:
- View the Collection
- Import a Copy of the Collection
- Fork the Collection
- Download Collection from GitHub Page
Let’s look at each of the above methods in detail.
View the Collection
This option allows you to just view (and not try out) the API requests of the Postman collection.
Perform the following steps to view the Automate Management API Postman collection:
- Click the View collection link in the Fork collection into your workspace modal.
A new tab opens up in your browser where you should see the latest collection preloaded in the left navigation.
Note: If you want to try out the API requests, you can either import a copy of the collection or fork the collection.
Import a Copy of the Collection
This option allows you to import a copy of the collection into your workspace.
To import the Automate Management API collection, perform the following steps:
- Click the import a copy link in the Fork collection into your workspace modal.
- In the resulting Import Collection modal within the Postman app, select a workspace and click Import to import the latest Postman collection into your selected workspace.
You will see a copy of the latest Postman collection in the left navigation panel.
Fork the Collection
This option allows you to fork, or create a copy of the collection, and perform changes to the collection without affecting the original.
To fork the Automate Management API collection, perform the following steps:
- Click the Fork Collection button in the Fork collection into your workspace modal.
- This opens the Sign In page. You can either enter your login credentials and click Sign in, or sign in using your Google account or via SSO.
- In the resulting Fork collection modal, if needed, enter a Fork label that lets you uniquely identify your collection and select a Workspace.
Under Notifications, check Watch original collection to get notified of any changes that are made to the original collection.
Once done, click Fork Collection to fork the Postman collection into your selected workspace.
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 the following Watch button and select Watching.
Configure Environment Variables
When you download and install the latest version of the Automate Management API Postman Collection, you also download and import the respective environment along with the environment variables.
Once your Environment is imported, next you need to set your Automate 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 | automations-api.contentstack.com |
| organization_uid | your_organization_uid |
| authtoken | your_authtoken |
Note: The Automate Postman Collection will require a valid Authtoken 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:
- Identify the environment variables that you want to define.
- In the top right corner of Postman, click on the environment's dropdown and select Automate Management API - Environment.
- Click the "eye" icon present in the top right corner of Postman. It opens up in the environment variables modal. Click Edit to make changes in the variables.
- In the VARIABLE field, enter the name of the environment variable. In the INITIAL VALUE field, enter your Automate-account-specific value that will replace the variable when the call is made.
- Once you have defined your variables, click Save.
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.
Next, let’s see how you can run API Requests from your Automate Postman collection using your environment.
Make an API Request
With the Automate Postman Collection loaded into the Postman app (on the left panel) and the environment created, you can now make API requests to the Automate API via Postman.
To make an API request, perform the following steps:
- Select the respective environment, Automate Management API - Environment, from the dropdown.
- Select an API Request from the Automate Postman Collection. In this example, we will use the Get all projects request which is a part of the Projects folder.
Note: If you want to make changes to your parameters or want to add parameters of your own, you can do it here.
- Next, click Send at the top right to make the API request.
The API call should return with a response under the Body tab in the bottom half of the screen.
Secure Organization UID and Tokens
We strongly advise against storing your Organization UID and authtokens 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 Automate account-specific Organization UID 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:
- Click Cookies on the far right corner.
- In the Cookies modal under the Manage Cookies tab, click the Domains Allowlist at the bottom left.
- Add automations-api.contentstack.com and click Add.
This will allow you to access cookies of this domain in scripts programmatically.
Note: To avoid this situation, we recommend you to use the Organization UID along with the Authtoken to make valid Automate 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.
