cs-icon.svg

Automation Hub Management API

Introduction

Base URL

  • US (North America, or NA): https://automations-api.contentstack.com/
  • Europe (EU): https://eu-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

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 Automation Hub Management API.

The Automation Hub 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 Automation Hub Management API, you need to authenticate yourself with an Authtoken. Read more about it in Authentication.

Note: The initial release of the Automation Hub 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 Automation Hub 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 Automation Hub 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 Automation Hub 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.
  • Automation Hub 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, Automation Hub returns an error.

Automation Hub 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 Automation Hub's servers; it is very rare though.

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

HTTP status codeDescription
400 Bad RequestThe request was incorrect or corrupted.
401 Access DeniedThe login credentials are invalid.
403 Forbidden ErrorThe page or resource that is being accessed is forbidden.
404 Not FoundThe requested page or resource could not be found.
429 Rate Limit ExceededThe number of requests exceeds the allowed limit for the given time period.
422* Unprocessable Entity (also includes Validation Error and Unknown FieldThe request is syntactically correct but contains semantic errors.
500 Internal Server Error The server is malfunctioning and is not specific on what the problem is.
502 Bad Gateway ErrorA server received an invalid response from another server.
504 Gateway Timeout ErrorA 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 Automation Hub error codes that are used for internal purposes.

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.

Was this article helpful?
^

Sample Request

Response
Body
PrettyRaw