Brand Kit - Introduction

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 documentation provides information on endpoints, operations, parameters, and responses for the Brand Kit Management API. It includes details for creating, fetching, updating, and deleting Brand Kits and Voice Profiles.

Brand Kit is a powerful tool that serves as a centralized hub for your organization's brand identity, encompassing detailed brand information and persona guidelines. You can create, view, update, and delete multiple Brand Kits via the API requests documented.

Voice Profile lets you create distinct AI-generated brand voices for your content. You can use the API requests in this doc to manage these profiles within a Brand Kit.

Learn more about Brand Kit.

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

Brand Kit uses token-based authentication. You can use the Authtoken along with the Organization UID to make API requests. Read more about the different types of tokens.

• Pass the user Authtoken against the authtoken parameter as header.
• Pass the OAuth Token value against the authorization parameter as header.
• Pass the Organization UID against the organization_uid parameter as header for performing CRUD operations on Brand Kits.
• Pass the Brand Kit UID against the brand_kit_uid parameter as header for performing CRUD operations on Voice Profiles.

To retrieve the authtoken, log in to 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 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.

NoteIf 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 into 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. Only the owner of the organization and users with permission to access the Organization without SSO can use these APIs. Learn more about REST API Usage.

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

By default, the Brand Kit Management API enforces the following rate limits:

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.

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

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

Brand Kit 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 our servers; it is very rare though.

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

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

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

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