Brand Kit Management APINEW
Introduction
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 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, processing prompts using Gen AI, and ingesting, updating, deleting and getting usage from the Knowledge Vault.
Let’s look at what each of these APIs are:
- 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.
- The Generative AI API requests link your Vector database with a Large Language Model (LLM) processing prompts and returning relevant data.
- The Knowledge Vault API requests acts as a central repository for brand-related data, offering content ingestion, usage tracking, updating, and deletion functionalities.
Base URL
For Brand Kit and Voice Profile APIs
- US (North America, or NA): https://brand-kits-api.contentstack.com
For Gen AI and Knowledge Vault APIs
- US (North America, or NA): https://ai.contentstack.com/brand-kits
Authentication
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.
For Authtoken-based authentication
- 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.
How to Get Authtoken
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.
Note: 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 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 Limiting
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:
| API Request | Rate Limit |
|---|---|
Brand Kit Read (GET) and Write (POST/PUT/DELETE) requests | 10 requests per second per organization |
GenAI Write (POST) requests | 600 requests per minute per organization |
Knowledge Vault Write (POST) 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 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.
Errors
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.
| HTTP status code | Description |
|---|---|
| 400 Bad Request | The request was incorrect or corrupted. |
| 401 Unauthorized User | The user is not authorized. |
| 403 Forbidden Error | The page or resource that is being accessed is forbidden. |
| 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. |
Using Postman Collection
Contentstack offers you a Postman Collection that helps you try out our Brand Kit Management API.
This feature is coming soon! Please watch this space for further updates.
API Reference
Brand Kit
Brand Kit serves as a centralized repository for your organization's brand identity and guidelines, offering a comprehensive array of product details and overall brand persona. By using the API requests, you can create, view, update, and delete one or more Brand Kits.
Create Brand Kit
The Create Brand Kit request lets you create a new Brand Kit in the specified organization.
To configure the permissions for your application via OAuth, include the brand-kits:manage scope.
Here’s an example of the Request Body for creating a new Brand Kit:
{
"brand_kit": {
"name": "Sample Brand Kit",
"description": "This is a sample Brand Kit created for testing",
"api_keys": [
"bxxxxxxxxxxxx9",
"bxxxxxxxxxxxx9"
]
}
}
Get All Brand Kits
The Get All Brand Kits request fetches the list of all the Brand Kits in an organization.
To configure the permissions for your application via OAuth, include the brand-kits:read scope.
Get a Single Brand Kit
The Get a Single Brand Kit request fetches the details of a specific Brand Kit in an organization.
To configure the permissions for your application via OAuth, include the brand-kits:read scope.
Update Brand Kit
The Update Brand Kit request lets you update an existing Brand Kit in an organization.
To configure the permissions for your application via OAuth, include the brand-kits:manage scope.
Here’s an example of the Request Body that you can use to update a Brand Kit:
{
"brand_kit": {
"name": "Sample Brand Kit",
"description": "This is the updated description for Sample Brand Kit",
"api_keys": [
"bxxxxxxxxxxxx9"
]
}
}
Delete Brand Kit
The Delete Brand Kit request lets you delete an existing Brand Kit in an organization.
To configure the permissions for your application via OAuth, include the brand-kits:manage scope.
Voice Profile
Voice Profiles allows you to define unique AI-generated brand voices that you can apply to your content. By using the API requests, you can create, view, update, and delete the Voice Profile in a Brand Kit.
Create Voice Profile
The Create Voice Profile request lets you create a new Voice Profile in a Brand Kit within an organization.
To configure the permissions for your application via OAuth, include the brand-kits:manage scope.
Here’s an example of the Request Body for creating a new Voice Profile:
{
"voice_profile": {
"name": "Sample Voice Profile",
"description": "This is the sample description for new Voice Profile.",
"communication_style": {
"formality_level": 4,
"tone": 3,
"humor_level": 2,
"complexity_level": 1
}
}
}
Get All Voice Profiles
The Get All Voice Profiles request fetches the list of all Voice Profiles in a Brand Kit within an organization.
To configure the permissions for your application via OAuth, include the brand-kits:read scope.
Get a Single Voice Profile
The Get a Single Voice Profile request fetches the specific Voice Profile from a Brand Kit in an organization.
To configure the permissions for your application via OAuth, include the brand-kits:read scope.
Update Voice Profile
The Update Voice Profile request lets you update an existing Voice Profile from the Brand Kit in an organization.
To configure the permissions for your application via OAuth, include the brand-kits:manage scope.
Here’s an example of the Request Body for updating a Voice Profile:
{
"voice_profile":{
"description": "Test Brand Kit Description",
"insights": "Sample Insights",
"sample_content": "Sample Content",
"communication_style": {
"complexity_level": 1,
"formality_level": 2,
"humor_level": 3,
"tone": 4
}
}
}
Delete Voice Profile
The Delete Voice Profile request lets you delete an existing Voice Profile from the Brand Kits in an organization.
To configure the permissions for your application via OAuth, include the brand-kits:manage scope.
Generative AI
The Generate AI works as a communication channel between your Vector database and Large Language Model (LLM). It carries your prompt/action to the vector database, retrieves a chunk of data based on the prompt/command, forwards it to the LLM for it to process, and finally returns the processed data back to the field.
GenAI
The GenAI request carries prompts, processes them, retrieves relevant data, and returns the processed data.
To configure the permissions for your application via OAuth, include the brand-kits:read scope.
Here’s an example of the Request Body for using GenAI request:
{
"prompt": "Enter your prompt",
"knowledge_vault": true,
"voice_profile_uid":"cs************d"
}
Knowledge Vault
Knowledge Vault works as a centralized repository where you can store, manage, and organize brand-related data. You can use the Ingest Content, Get Content Usage, Update Content, and Delete Content requests.
Ingest Content
The Ingest Content request lets you add content in the Knowledge Vault.
To configure the permissions for your application via OAuth, include the brand-kits:manage scope.
Get Content Usage
The Get Content Usage request lets you fetch the details of content being used from the Knowledge Vault.
To configure the permissions for your application via OAuth, include the brand-kits:manage scope.
Update Content
The Update Content request lets you update a specific content stored in the Knowledge Vault.
To configure the permissions for your application via OAuth, include the brand-kits:manage scope.
Delete Content
The Delete Content lets you delete a specific content stored in the Knowledge Vault.
To configure the permissions for your application via OAuth, include the brand-kits:manage scope.
