Introduction

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

This document is a detailed reference to Contentstack’s Content Delivery API.

The Content Delivery API is used to retrieve content from your Contentstack account and deliver it to your web or mobile properties. If you are looking for APIs to manage content, you should use the Content Management API.

Our APIs serve content via a powerful and robust content delivery network (CDN). Multiple datacenters around the world store a cached copy of your content. When a page request is made, the content is delivered to the user from the nearest server. This greatly accelerates content delivery and reduces latency.

The CDN includes many points of presence (POPs) located in high-density internet exchange regions around the world. These POPs are continually expanding to ensure faster and more reliable content delivery.

Warning We only support version 3 on the CDN. If you're still using version 2 (which we recommend you should not), switch to the CDN version for even faster loading. And, we have a URL size limitation of 8KB on API Requests that hit our CDN services. Any Request URL that goes above this size limit will receive the 414 - URI Too Long error response. Please make sure you limit the size of your API Requests.

Contentstack provides SDKs, API references, getting started guides, and sample apps for popular programming languages and platforms. These resources help you build applications and fetch content efficiently using the Content Delivery API.

The SDKs are read-only and are designed to retrieve published content from the nearest server via the global CDN.

You will find a list of all the available SDKs under the Development Resources and SDKs section.

We provide SDKs for the following platforms:

• iOS
• Java
• Android
• PHP
• JavaScript (Browser)
• Ruby
• NodeJS
• .NET
• React Native
• Python
• Dart

The process for building sample apps and working with the SDKs differ based on the platform. We have covered them in detail in their respective sections.

Since the Content Delivery APIs (CDAs) are private APIs, you will need to pass the following as HTTP headers to make authorized CDA requests:

• The Delivery Token of the concerned environment (against the access_token key)
• The stack API Key

The API Key is a unique key assigned to each stack. The Delivery Token is a read-only credential that you can create for different environments of your stack.

While Content Delivery API requests may work with Access Token (instead of Delivery Token), we strongly recommend that you not use it, since we have already deprecated Access Token for new stacks.

NoteThe nomenclature for the use of delivery tokens in CDA requests will remain the same, i.e. you need to pass the value of the delivery token against the access_token key.

NoteWe have deprecated the usage of Access Tokens for all stacks. We strongly recommend that you use Delivery Tokens for fetching published content via the Content Delivery API and Management Tokens for fetching draft content via the Content Management API.

To retrieve the stack API key and the delivery token of a specific publishing environment of your stack, perform the steps given below after logging into your Contentstack account:

1. Go to your stack.
2. Navigate to Settings > Tokens > Delivery Tokens.
3. From the list of existing delivery tokens, click on the Delivery Token that applies to the publishing environment of your choice.
   
4. At the bottom of the resulting page, you will see the API Key and Delivery Token of your stack.
   

   Additional ResourceRead more about how you can create a new delivery token.

NoteOnly the stack owners, developers, and admin can create delivery tokens.

Rate limiting defines the maximum number of API requests your organization can make within a specific time frame.

Request Types

• CDN Requests: Contentstack’s CDN serves cached responses. These requests are not subject to rate limiting.

• Origin Server Requests: Requests that are not cached and are routed to the origin server are subject to rate limits.

Default Limits

By default, origin server requests are limited to 80 requests per second per organization. All requests made from the CDA and Image Delivery API endpoints counts towards this rate limit excluding GraphQL. The exact rate limit depends on your plan. If required, you can request an increase by contacting support.

NoteWhile CDN requests are not rate-limited, all API requests (CDN and origin) count toward your organization’s overall API usage quota.

Rate Limit Exceeded

If your application exceeds the allowed rate limit within a given time period, the API will return an HTTP 429 (Too Many Requests) response.

Monitoring Rate Limits

You can track your current rate limit status using the HTTP response headers returned with each API request. These limits reset at the beginning of each time window.

• The base URL for Content Delivery API for different regions can be found in the Base URL section.
• The API version (in our case, 'v3') can be found in the URL, e.g. cdn.contentstack.io/v3/endpoint.
• Only GET verb or methods are recommended on cdn.contentstack.io.
• URL paths use lower case and all the operations are specified in URL query parameters such as count, include_count, and query.
• Query parameters are case sensitive and uses lower case, underscore (_) separated 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. Read more about it in the HTTP Headers section.

HTTP headers let the client and the server pass additional information with an HTTP request or response. An HTTP header consists of its case-insensitive name followed by a colon (:), then by its value.

Here’s what an HTTP response body looks like:

< x-served-by: cache-lax8631-LAX, cache-bur17525-BUR
< x-cache: MISS, HIT
< x-cache-hits: 0, 1
< x-runtime: 27ms
< age: 5182
< x-timer: S1557441707.643683,VS0,VE0

Let’s understand what the above HTTP Header means:

• x-served-by: cache-lax8631-LAX, cache-bur17525-BUR

  Two cache-nodes in X-Served-By show that shielding is turned on, with cache-lax8631-LAX serving as the delivering cache node at the "shield" datacenter and cache-bur17525-BUR serving as the delivering cache node at the "local" datacenter.

• < x-cache: MISS, HIT

  The X-Cache: MISS, HIT indicates that the requested object was not in the shield cache (a MISS) but was in the local delivering node (a HIT). For more details, refer Understanding cache HIT and MISS headers with shielded services.

• < x-cache-hits: 0, 1

  The X-Cache-Hits reflects that same “MISS, HIT” information in numeric format as 0, 1.

• < x-runtime: 27ms

  The X-Runtime HTTP response header provides the time (in milliseconds) an application takes to process a request.

• < age: 5182

  Age denotes a non-negative integer that represents the time in seconds the object has been in a proxy cache.

• < x-timer: S1557441707.643683,VS0,VE0

  The X-Timer header provides the timing information about the journey of a request from end to end.
  The above header can be broken down into three parts, each separated by commas:
  • S1557441707.643683: The first section of the header (starting with S) represents a Unix timestamp of the start of the request on our edges.
  • VS0: The next section, VS or "varnish start," represents the start of the varnish part of the request's journey and will always be 0.
  • VE0: The last section, VE or "varnish end," represents the sum of the length of the trip. For cache HITs, the length of the trip will nearly always be 0 (not actually zero, but less than a millisecond is rounded down).
    For cache MISSs, this number represents the number of milliseconds it took to retrieve the data from your origin server and send the response back to the requester.
    For more information, you can refer to the Understanding the X-Timer header guide.

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 codes and their meanings.

* Contentstack returns the 422 HTTP status code for an error along with the "UID is not valid" message in the response body either when an entry doesn’t exist within the stack, has been deleted from the content type, or exists within a different content type. As the entry has been deleted or unpublished, the Content Delivery Network (CDN) cannot identify the specified entry UID through the cache servers. To check whether the entry has been deleted, try retrieving the entry from CDN first. If the API request fails to retrieve the entry from CDN, then make an API request to the Origin server to check whether the entry exists.

Also, if the content type doesn't exist within the stack, Contentstack returns the 422 HTTP status code for an error along with the "UID is not valid" message in the response body.

** Here are a few use cases where you might get a 429 error:

• Fetching published uncached entries: When making requests to fetch published but uncached entries, the initial request goes to the origin, and subsequent requests are cached. There might be a chance that after publishing a large set of entries, you may get a 429 error for a few requests. But this should be resolved in some time as requests get cached based on the rate limit.
• Fetching unpublished entries / Passing requests with semantic errors: Fetching unpublished entries or passing incorrect parameters in the request URL can result in 422 errors as the server may be unable to process these requests correctly. For example, if a user makes 200 incorrect requests to https://www.cdn.contentstack.io/. The initial 100 requests will give the 422 error because the requests are uncached, also since all the requests are incorrect and going to the origin, the other 100 requests will return 429 errors.

Note For uncached requests, the common rate limit is 100 requests per second per organization.

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

Learn more about how to get started with using the Postman Collection for Contenstack Content Delivery API.

Contentstack provides the OpenAPI files of the Contentstack’s Content Delivery APIs (CDA) that you can use to try out Contentstack APIs on any OpenAPI platform such as Swagger. You can download the OpenAPI JSON file of the Content Delivery API and open it on Swagger Editor to start using it.

Learn more about how to get started with using the OpenAPI files for Contenstack Content Delivery API.