Assets API - Introduction

• AWS North America (AWS NA): https://am-api.contentstack.io
• AWS Europe (EU): https://eu-am-api.contentstack.com
• Azure North America (Azure NA): https://azure-na-am-api.contentstack.com
• GCP North America (GCP NA): https://gcp-na-am-api.contentstack.com

Assets is a centralized platform designed for organizing, managing, and enriching digital assets such as images, documents, videos, and much more. It supports structured asset grouping through spaces and folders, enhances asset metadata via custom fields and types, and enables localization through locale management. 

The Assets APIs enable you to manage digital assets such as files, folders, metadata fields, asset types, and localization settings. Each section below outlines a set of related operations, including request structure, headers, parameters, and example responses.

The Assets API accepts two authentication methods. Choose one per request.

NoteManagement tokens do not work with the Assets API. Use an authtoken or an OAuth access token.

• Pass a Contentstack authtoken against the authtoken header.
• Pass 4 against the x-cs-api-version header.

• Pass the OAuth access token against the authorization header, prefixed with Bearer.
• Pass 4 against the x-cs-api-version header.

Neither header is individually mandatory, but one of them is always required. A request that carries neither fails with 401.

Requests that operate outside a space need the organization_uid header to identify the organization. This applies to the asset type, field, space list, and search endpoints. Requests addressed to a single space, such as those under /spaces/{space_uid}/assets, do not need it.

Contentstack OAuth employs the OAuth 2.0 protocol, enabling external applications to access Contentstack APIs on behalf of users. It issues access tokens (App and User tokens) to client applications, allowing them to retrieve restricted data from the Contentstack resource server without the need for the resource owner to share their credentials. Learn more about Contentstack OAuth and OAuth Scopes.

To retrieve the authtoken, log in to your Contentstack account by using the "Log in to your account" request. This request returns the authtoken in the response body.

These tokens do not have an expiration time limit. However, there is a maximum limit of 20 valid tokens per account at a time. If you already have 20 valid tokens, creating a new authtoken causes the oldest one to expire without warning.

For SSO-enabled organizations, the "Log in to your account" request does not return the user authtoken for users who access the organization through Identity Provider login credentials. Only the owner of the organization and users with permission to access the organization without SSO can use these requests. Learn more about REST API Usage.

To get the OAuth token, perform the steps given within the Configuring Contentstack OAuth section after logging into your Contentstack account.

NoteOnly the organization Owner and Admin users can create OAuth Tokens.

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.

NoteBulk actions do not follow the standard CMA rate limit of 10 requests per second. The default rate limit for bulk actions is 1 request per second i.e., in one second you can make only one bulk action API request.

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.

• The base URL for Assets API for different regions can be found in the Base URL section.
• The API version (in our case, 'v4') can be found in the URL, e.g. am-api.contentstack.io/v4/endpoint.
• The Assets 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.

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.

* Contentstack returns the 422 HTTP status code with the "UID is not valid" message when an entry doesn’t exist, has been deleted, or belongs to a different content type. To check if an entry has been deleted, first try retrieving it from the CDN, then from the origin server if needed. This error can also occur due to invalid query parameters, such as using an empty array with logical operators like $and. Always ensure your queries contain valid conditions. For example, {"$and": [{}, {}]} is not a valid query.

NoteThe 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.