Content Delivery API

Overview

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.

We have partnered with Fastly as our CDN. It has powerful points of presence (POPs), strategically placed in the highest density internet exchange points across the world. They have 17 POPs in North America, 8 in Asia, 10 in Europe, 2 in Africa, 6 in Australia and New Zealand, and 6 in South America.

Note: Only version 3 is supported 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.

Authentication

Since the Content Delivery APIs (CDAs) are private APIs, you will need the stack API Key and the delivery token of the concerned environment to make requests.

The API Key is a unique key assigned to each stack. The Delivery Token is a read-only credential that you create for each environment of your stack. You need to pass the stack API Key and the environment delivery token as HTTP headers to authenticate your request.

To retrieve these values, log in to your Contentstack account and navigate to SETTINGS > STACK.  You will find the stack API key there. Only the Developers and Stack Owners can view the the API key.

To create new delivery token or view existing tokens, navigate to SETTINGS > Tokens. Please note that the delivery token is a read-only token. This means that this token can be used to fetch published content only, and not to edit or create new content in your stack. Learn more about delivery tokens.

Note: You can use Access Tokens as well as Delivery Tokens in the Content Delivery API calls. Read the FAQs to learn the difference between the two. To use Delivery Tokens in the calls given below, use the value of the delivery token against the access_token key. 

Rate Limiting

The rate limit is the maximum number of requests that you can make using Contentstack’s API in a given period. There are no limits on the requests that you make to the cached data on Contentstack’s CDN. Contentstack's API automates caching to enable our API to scale. For uncached requests, i.e., requests to the origin server, there is a maximum limit of 100 requests per second per organization. The rate limit depends on your plan, and you can request an increase in your rate limit if necessary.

API conventions

• The base URL for Content Delivery API is cdn.contentstack.io.
• 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 code it returns.
• Along with the HTTP status codes, additional information, such as whether cache was hit or missed, is also included in the HTTP response body as follows:

  < x-served-by: cache-lax8631-LAX, cache-bur17525-BUR
  < x-cache: MISS, HIT
  < x-cache-hits: 0, 1

  For more details, refer Understanding cache HIT and MISS headers with shielded services.

Errors

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.

Content Types

Content type defines the structure or schema of a page or a section of your web or mobile property. To create content for your application, you are required to first create a content type, and then create entries using the content type. Read more about Content Types.

All Content Types

Get all content types

Try

This call returns comprehensive information of all the content types available in a particular stack in your account.

Single Content Type

Get a single content type

Try

This call returns information of a specific content type. It returns the content type schema, but does not include its entries.

Entries

An entry is the actual piece of content created using one of the defined content types. Read more about Entries.

All Entries

Get all entries

Try

The Get all entries call fetches the list of all the entries of a particular content type. It also returns the content of each entry in JSON format. You can also specify the environment and locale of which you wish to get the entries.

You can add queries to extend the functionality of this API call. Under the URI Parameters section, insert a parameter named query and provide a query in JSON format as the value.

To learn more about the queries, refer to the Queries section.

Note: This request returns only the first 100 entries of the specified content type. If you get more than 100 items in your response, refer the Pagination section to retrieve all your entries in paginated form. Also, to include the publish details in the response, make use of the include_publish_details parameter and set its value to ‘true’. This query will return the publish details of the entry in every environment along with the version number that is published in each of the environment.

Single Entry

Get a single entry

Try

The Get a single entry request fetches a particular entry of a content type.

Note: If no version is mentioned, this request will retrieve the latest published version of the entry. To retrieve a specific version, make use of the version parameter and keep the environment parameter blank.

Assets

Assets refer to all the media files (images, videos, PDFs, audio files, and so on) uploaded in your Contentstack repository for future use. These files can be attached and used in multiple entries. Learn more about Assets.

All Assets

Get all assets

Try

This call fetches the list of all the assets of a particular stack. It also returns the content of each asset in JSON format. You can also specify the environment of which you wish to get the assets.

You can apply queries to filter assets/entries. Refer to the Queries section for more details.

Single Asset

Get a single asset

Try

This call fetches the latest version of a specific asset of a particular stack.

Note: If no version is mentioned, this request will retrieve the latest published version of the asset. To retrieve a specific version, make use of the version parameter and keep the environment parameter blank.

Synchronization

The Sync API takes care of syncing your Contentstack data with your app and ensures that the data is always up-to-date by providing delta updates.

Note: When executing the following synchronization API Requests, you need to pass the Delivery Token as the value to the access_token parameter.

Initial Synchronization

Initial Sync

Try

The Initial Sync request syncs the entries and assets of a stack, published on a specific environment.

Set init to ‘true’ if you want to sync all the published entries and assets. This is usually used when the app does not have any content and you want to get all the content for the first time.

Note: When executing the API request, pass the Delivery Token as the value to the access_token parameter.

Applicable parameters:

Parameter	Values
content_type_uid	Enter content type UIDs. e.g., products This retrieves published entries of specified content type.
locale	Enter locale codes. e.g., en-us This retrieves published entries of specific locale.
start_from	Enter the start date. e.g., 2018-08-14T00:00:00.000Z This retrieves published entries starting from a specific date.
type	Applicable values are: entry_published asset_published entry_unpublished asset_unpublished entry_deleted asset_deleted content_type_deleted If you do not specify any value, it will bring all published entries and published assets.

Note: If you specify any value for content_type_uid, locale, start_from, or type, the values for these parameters will remain unchanged for all subsequent sync requests.

Once you perform an initial sync, you will either get a sync_token or a pagination_token in response. These tokens don't have an expiry time.

You can use the sync_token later to perform subsequent sync, which fetches only new changes through delta updates.

If there are more than 100 records, you get a pagination_token in response. This token can be used to fetch the next batch of data. Read Sync using pagination token for more details.

Sync using pagination token

Sync using pagination token

Try

When running the Initial Synchronization or the Subsequent Sync request, if the result of the sync (initial or subsequent) request exceeds 100 records you will get a pagination_token.

The Sync using pagination token request uses the pagination_token to retrieve the next batch of data (100 records) while performing the sync. You can reiterate the process until you get a sync_token.

Note: When executing the API request, pass the Delivery Token as the value to the access_token parameter.

Subsequent Sync

Subsequent Sync

Try

The Subsequent Sync request is used to retrieve the updated content (i.e., published or unpublished content, or any published content that has been deleted) since the last performed complete Sync.

In this API request, you need to provide the sync_token that you received in the last complete sync process. If there are more than 100 records, you will get a pagination_token instead. This token can be used to fetch the next batch of data. Refer the Sync using pagination token section for more details.

Note: Once you have performed the Initial Sync process, you do not need to perform it again. For retrieving the subsequent delta changes, use the sync_token received either in the Initial Sync process or the previous Subsequent Sync requests to sync new changes. Also, when executing the API request, pass the Delivery Token as the value to the access_token parameter.

Queries

Contentstack provides certain queries that you can use to fetch filtered results. You can use queries for Entries and Assets API requests. 

Equals Operator

Get entries containing the field values matching the condition in the query.

Example: In the Products content type, you have a field named Title ("uid":"title") field. If, for instance, you want to retrieve all the entries in which the value for the Title field is 'Redmi 3S', you can set the parameters as:

{"title": "Redmi 3S"}

Let’s consider another example. You want to retrieve all the entries that have their start date as 8th December, 2017. Now, you need to set this parameter with the date in the ISO Date format as below:

{ "start_date": "2017-12-08T00:00:00.000Z" }

This will give you all the entries where the start date is 8th December, 2017.

Equals Operator

Try

Equals Operator Within Group

Get entries where the value of a field within a Group field matches the condition in the query. This query is specifically for fields that are part of the Group field.

Example: In the Products content type, we have a Group field named Bank Offers ("uid":"bank_offers"). And, within this Group field, we have a subfield named Card Type ("uid":"card_type"). If, for instance, you want to retrieve the entries in which the value for the Card Type field is 'Debit Card', you can use the following value in the ‘query’ parameter:

{"bank_offers.card_type": "Debit Card"}

Equals Operator Within Group

Try

Equals Operator Within Modular Blocks

Get entries where the value of a field within a Modular Blocks field matches the condition in the query. This query is specifically for fields that are part of the Modular Blocks field.

Example: In the Products content type, we have a Modular Blocks field named Additional Info ("uid":"additional_info") that contains the Deals ("uid":"deals") block. And, within this Deals block, we have a field named Deal Name ("uid":"deal_name"). If, for instance, you want to retrieve the entries in which the value for the Deal Name field is 'Christmas Deal', you can use the following value in the query parameter:

{"additional_info.deals.deal_name": "Christmas Deal"}

Equals Operator Within Modular Blocks

Try

Not-equals Operator

Get all the entries in which the value of a field does not match the value provided in the condition.

Example: In the Product content type, you have a field named Price in USD. Now, you need to retrieve all entries where the value of this field not equal to '146' for this field. The parameter can be used as:

{ "price_in_usd": { "$ne": 146 } }

This will give you all the entries that have the value for Price in USD not set to '146'.

Let’s consider another example. You want to retrieve all the entries except the ones that have their start date as 8th December, 2017. Now, you need to set this parameter with the date in the ISO Date format as below:

{ "start_date": { "$ne": "2017-12-08T00:00:00.000Z" } }

This will give you all the entries where the start date is not 8th December, 2017.

Not-equals Operator

Try

Not-equals Operator Within Group

Get entries where the value of a field does not match the value provided in the condition. This query is specifically for fields that are part of the Group field.

Example: In the Products content type, we have a Group field named Bank Offers ("uid":"bank_offers"). And, within this Group field, we have a subfield named Card Type ("uid":"card_type"). If, for instance, you want to retrieve the entries in which the value for the Card Type field is NOT 'Debit Card', use the following value in the query parameter:

{"bank_offers.card_type": {"$ne": "Debit Card"}}

Not-equals Operator Within Group

Try

Not-equals Operator Within Modular Blocks

Get entries where the value of a field within the Modular Blocks field matches the condition in the query. This query is specifically for fields that are part of any block within a Modular Block field.

Example: In the Products content type, we have a Modular Group field named Additional Info ("uid":"additional_info") that contains the Deals ("uid":"deals") block. And, within this Deals block, we have a field named Deal Name ("uid":"deal_name"). If, for instance, you want to retrieve the entries in which the value for the Deal Name field is NOT 'Christmas Deal', use the following value in the query parameter:

{"additional_info.deals.deal_name": {"$ne": "Christmas Deal"}}

Not-equals Operator Within Modular Blocks

Try

Array Equals Operator

Get entries is which the value of a field matches to any of the given values. This parameter will compare field values of entries to that of the values provided in the condition.

Example: In the Product content type, you have a field named Price in USD. Now, you need to retrieve all the entries where value of this field is one among the given set of values. The query fired using the '$in' parameter is given below:

{ "price_in_usd": { "$in": [ 101, 749 ] } }

This will retrieve all the entries that have the value of Price in USD field set to '101' or 749'.

Array Equals Operator

Try

Array Equals Operator Within Group

Get entries where the value of a field, within a Group field, matches any of the given values. This parameter will compare field values of entries to that of the values provided in the condition. This query is specifically for fields that are part of the Group field.

Example: In the Products content type, we have a Group field named Bank Offers ("uid":"bank_offers"). And, within this Group field, we have a subfield named Card Type ("uid":"card_type"). If, for instance, you want to retrieve the entries in which the values for the Card Type field are ‘Credit Card’ and 'Debit Card', use the following value in the query parameter:

{"bank_offers.card_type": {"$in": ["Credit Card", "Debit Card"]}}

Array Equals Operator Within Group

Try

Array Equals Operator Within Modular Blocks

Get entries where the value of a field within Modular Blocks matches to any of the given values. This query is specifically for fields that are part of any block within a Modular Block field.

Example: In the Products content type, we have a Modular Group field named Additional Info ("uid":"additional_info") that contains the Deals ("uid":"deals") block. And, within this Deals block, we have a field named Deal Name ("uid":"deal_name"). If, for instance, you want to retrieve the entries in which the values for the Deal Name field are 'Christmas Deal’ and ‘Summer Deal', use the following value in the query parameter:

{"additional_info.deals.deal_name": {"$in": ["Christmas Deal", "Summer Deal"]}}

Array Equals Operator Within Modular Blocks

Try

Array Not-equals Operator

Get all entries in which the value of a field does not match to any of the given values. This parameter will compare field values of entries to that of the values provided in the condition, and the query will retrieve entries that have field values that does not match to any of the values provided.

Example: In the Product content type, you have a field named Price in USD. Now, you need to retrieve the entries where the field value does not fall in the given set. You can send the parameter as:

{ "price_in_usd": { "$nin": [ 101, 749 ] } }

This will give you all the entries that do not have the value for Price in USD set to '101' or '749'.

Array Not-equals Operator

Try

Array Not-equals Operator Within Group

Get entries in which the value of a field does not match any of the values provided in the condition. This query is specifically for fields that are part of the Group field.

Example: In the Products content type, we have a Group field named Bank Offers ("uid":"bank_offers"). And, within this Group field, we have a subfield named Card Type ("uid":"card_type"). If, for instance, you want to retrieve the entries in which the values for the Card Type field are NOT ‘Credit Card’ and 'Debit Card', use the following value in the query parameter:

{"bank_offers.card_type": {"$nin": ["Debit Card", "Credit Card"]}}

Array Not-equals Operator Within Group

Try

Array Not-equals Operator Within Modular Blocks

Get entries where the values of the fields within Modular Blocks match the condition in the query. This query is specifically for fields that are part of any block within a Modular Block field.

Example: In the Products content type, we have a Modular Group field named Additional Info ("uid":"additional_info") that contains the Deals ("uid":"deals") block. And, within this Deals block, we have a field named Deal Name ("uid":"deal_name"). If, for instance, you want to retrieve the entries in which the values for the Deal Name field are NOT 'Christmas Deal’ and ‘Summer Deal', use the following value in the query parameter:

{ "additional_info.deals.deal_name": { "$nin": [ "Christmas Deal", "Summer Deal" ] } }

Array Not-equals Operator Within Modular Blocks

Try

Include Reference

When you fetch an entry of a content type that has a reference field, by default, the content of the referred entry is not fetched. It only fetches the UID of the referred entry, along with the content of the specified entry.

If you wish to fetch the content of the entry that is included in the reference field, you need to use the include[] parameter, and specify the UID of the reference field as value. This informs Contentstack that the request also includes fetching the entry used in the specified reference field.

In such a case, the API request would be as follows:

https://cdn.contentstack.io/v3/content_types/product/entries?include[]={reference_field_UID}

Example: In the Product content type, there is a reference field called Categories, which refers entries of another content type. Let’s assume that you had created an entry for the Product content type, and the value selected in the Categories field was ‘Mobiles’. If you fetch the entry using the ‘Get a Single Entry’ API request, you would get all the details of the entry in the response, but the value against the Categories field would be UID of the referenced entry (i.e., UID of the ‘Mobiles’ entry in this case).

In order to fetch the details of the entry used in the Categories reference field, you need to use the include[] parameter in the following manner:

https://cdn.contentstack.io/v3/content_types/product/entries?include[]=categories

In case you wish to fetch the data of the entries of multiple reference fields, use the include[] parameter in the following manner:

https://cdn.contentstack.io/v3/content_types/product/entries?include[]=categories&include[]=brands

Note: The maximum reference depth limit to which a multiple content type referencing Reference field works is one level deep.

Include Reference

Try

Include Reference for Nested Referenced Field

In case the referenced entry further has reference to another entry (nested referencing), you can use the dot operator to fetch the content of the nested references as well.

Example: Consider that you have a content type named ‘Blogs’ which has two reference fields (‘Authors’ and ‘Related Articles’) referring to the ‘Author’ and ‘Blogs’ content types (self-referencing), respectively. So, we have the following reference relationships between the content types:

• ‘Blogs’ refers to ‘Author’ content type
• ‘Blogs’ refers to ‘Blogs’ content type (self-referencing)

Now, consider that you want to retrieve an entry of the ‘Blogs’ content type along with the data of the author (details from the ‘Author’ content type) who authored the entry. You also want to fetch the data of the authors who wrote the ‘Related Articles’ as well that are referenced in this entry, (details from the ‘Blogs’ content type).

In this case, you need to use related_articles.authors in the include[] parameter.

https://cdn.contentstack.io/v3/content_types/content_type_uid/entries?include[]=authors&include[]=related_articles.authors

Include Reference Within Group

If the reference field is part of a Group field, you need to use the Group field UID as well as the reference field UID using a dot operator.

Example: In the Products content type, we have a Group field named Bank Offers ("uid":"bank_offers"). And, within this Group field, we have a Reference field named Bank ("uid":"bank"). If, for instance, you want to retrieve entries and include the data of the reference field as well, you need to use the include[] parameter in the following manner:

https://cda.contentstack.io/v3/content_types/product/entries?include[]=bank_offers.bank

Include Reference Within Group

Try

Include Reference Within Modular Blocks

If the reference field is part of a Modular Blocks field, you need to use the Modular Blocks UID, Block UID, as well as the reference field UID using a dot operator, as given below:

Example: In the Products’ content type, we have a Modular Group field named Additional Info ("uid":"additional_info") that contains the Related Products ("uid":"related_products") block. And, within this Block field, we have a field named Products ("uid":"products"). If, for instance, you want to retrieve entries and include the data of the reference field, you need to use the include[] parameter in the following manner:

https://cda.contentstack.io/v3/content_types/product/entries?include[]=additional_info.related_products.products

Include Reference Within Modular Blocks

Try

Reference Search Equals

Get entries having values based on referenced fields. This query retrieves all entries that satisfy the query conditions made on referenced fields.

Example: In the Product content type, if you wish to retrieve all entries that have their brand (Reference field) title set to Apple Inc. So, the query that needs to be run is given below:

{"brand": { "$in_query": { "title": "Apple Inc."}}}

If you have enabled multiple content type referencing, you need to mention the content type UID of the parent content type as follows:

{"brand": { "$in_query": { "title": "Apple Inc."}}, "_content_type_uid":"product"}

You can use queries within this query (nested querying) in order to query on the referred entries. In this case, the syntax of the query will be as follows:

{"reference_field_uid":{"$in_query":{"referred_content_type's_field_uid":{"query_to_be_applied"}}}, "_content_type_uid":"UID_of_referred_content_type"}

Additionally, to retrieve entries that also include references to entries of multiple content types, you need to specify the content type UIDs of all the referred entries when querying.

For example, “Parent Reference” has a Reference field that points to both “Reference content type 1” and “Reference content type 2”. Now, “Reference content type 1” has a field that refers to “Reference content type 3”.

So, to retrieve an entry in “Parent Reference” that has referred to an entry of “Reference content type 1” whose Reference field has referred an entry titled “Sample” of “Reference content type 3”. The query format is as follows:

{ "referred_parent_content_type_field_uid": { "$in_query": { "referred_content_type_1_field_uid": { "$in_query": { "title": "Sample" } }, "_content_type_uid": "referred_content_type_3_uid" }, "_content_type_uid": "referred_content_type_1_uid" }}

Reference Search Equals

Try

You can use queries within this query (nested querying) in order to to query on the referred entries. In this case, the syntax of the query will be as follows:

{"referred_content_type":{"$in_query":{"referred_fieldname":{"query_to_be_applied"}}"_content_type_uid":"UID_of_referred_content_type"}}

Example: So, extending our previous example, if you want to retrieve all entries that have their brand title that starts with ‘A’, you need to run the query given below:

{"brand":{"$in_query":{"title":{"$regex": "^/a", "$options": "i"}}}, "_content_type_uid":"UID_of_referred_content_type"}

In the above query, ‘Search by Regex’ query has been applied on the referred field. Other queries that can be applied are: Equals Operator, Equals Within Group Operator, Not-equals Operator, Array Equals Operator, Array Not-equals Operator, AND Operator, OR Operator, Less Than, Less Than Or Equal To, Greater Than, Greater Than Or Equal To, and Exists.

Reference Search Equals Within Group

Get entries having values based on referenced fields. This query retrieves all entries that satisfy query conditions made on referenced fields.

If the reference field is part of a Group field, you need to mention the Group field UID as well as the reference field UID using a dot operator, as given below.

Example: In the Products content type, we have a Group field named Bank Offers ("uid":"bank_offers"). And, within this Group field, we have a Reference field named Bank ("uid":"bank"). If, for instance, you want to retrieve the entries in which the value for the Bank field is ‘Citigroup,’ use the following value in the query parameter:

{"bank_offers.bank":{"$in_query":{"title":"Citigroup"}}, "_content_type_uid":"UID_of_referred_content_type"}

Reference Search Equals Within Group

Try

Reference Search Equals Within Modular Blocks

Get entries having values based on referenced fields. This query retrieves all entries that satisfy query conditions made on referenced fields.

If the reference is part of a Modular Blocks field, you need to mention the Modular Blocks UID, Block UID, as well as the reference field UID using a dot operator, as given below:

Example: In the Products content type, we have a Modular Group field named Additional Info ("uid":"additional_info") that contains the Related Products ("uid":"related_products") block. And, within this Related Products block, we have a field named Products ("uid":"products"). If, for instance, you want to retrieve the entries in which the values for the Title field is ‘iPhone 7 128GB', use the following value in the ‘query’ parameter:

{"additional_info.related_products.products":{"$in_query":{"title":"iPhone 7 128GB"}}, "_content_type_uid":"UID_of_referred_content_type"}

Reference Search Equals Within Modular Blocks

Try

Reference Search Not-equals

Get entries having values based on referenced fields. This query works the opposite of $in_query and retrieves all entries that does not satisfy query conditions made on referenced fields.

Example: Let’s say you wish to retrieve all entries that have brand names other than Apple Inc. So, the query that needs to be made is given below:

{"brand": { "$nin_query": { "title": "Apple Inc."} }, "_content_type_uid":"UID_of_referred_content_type"}

Note: When querying on Reference field, users need to specify the Content Type UID (using the_content_type_uid parameter) of entry to which the Reference field belongs to.

Reference Search Not-equals

Try

Reference Search Not-equals Within Group

Get entries having values based on referenced fields. This query works the opposite of $in_query and retrieves all entries that does not satisfy query conditions made on referenced fields.

If the reference is part of a Group field, you need to use the Group field UID as well as the reference field UID using a dot operator, as given below.

Example: In the Products content type, we have a Group field named Bank Offers ("uid":"bank_offers"). And, within this Group field, we have a Reference field named Bank ("uid":"bank"). If, for instance, you want to retrieve the entries in which the value for the Bank field is NOT ‘Citigroup', use the following query:

{"bank_offers.bank":{"$nin_query":{"title":"Citigroup"}}, "_content_type_uid":"UID_of_referred_content_type"}

Reference Search Not-equals Within Group

Try

Reference Search Not-equals Within Modular Blocks

Get entries having values based on referenced fields. This query works the opposite of $in_query and retrieves all entries that does not satisfy query conditions made on referenced fields.

If the reference is part of a Modular Blocks field, you need to use the Modular Blocks UID, Block UID, as well as the reference field UID using a dot operator, as given below:

Example: In the Products content type, we have a Modular Group field named Additional Info ("uid":"additional_info") that contains the Related Products ("uid":"related_products") block. And, within this Block field, we have a field named Products ("uid":"products"). If, for instance, you want to retrieve the entries in which the value for the Title field is NOT ‘iPhone 7 128GB', use the following query:

{"additional_info.related_products.products":{"$nin_query":{"title":"iPhone 7 128GB"}}, "_content_type_uid":"UID_of_referred_content_type"}

Reference Search Not-equals Within Modular Blocks

Try

Search by Regex

Get entries by using regular expressions to query fields of a content type. These regex queries will help to retrieve all the entries of a content type that have field values matching the condition provided in the query parameter.

Example: In the Product content type, you have a field named Color ("uid":"color") in your content type, and you want to retrieve all the entries within this content type that have values for this field starting with 'Bla'. You can use the parameter as:

{ "color": { "$regex": "^Bla" } }.

Now, in order to perform a case-insensitive search, you can use the $options key to specify any regular expressions options: 

{ "color": { "$regex": "^bla", "$options": "i" } }.

Note: Some useful values for $options are m for making dot match newlines and x for ignoring whitespace in regex.

Search by Regex

Try

Search by Regex Within Group

Get entries by using regular expressions to query fields of a Group field. These regex queries will help to retrieve all the entries of a content type that have field values matching the condition provided in the query parameter. This query is specifically for fields that are part of the Group field.

Example: In the Products content type, we have a Group field named Bank Offers ("uid":"bank_offers"). And, within this Group field, we have a Reference field named Bank ("uid":"bank"). If, for instance, you want to retrieve the entries in which the value for the Card Type field is NOT ‘Citigroup', use the following value in the query parameter:

{ "bank_offers.card_type": { "$regex": "^Credit Card" } }

Search By Regex Within Group

Try

Search by Regex Within Modular Blocks

Get entries by using regular expressions to query fields of a Modular Block. These regex queries will help to retrieve all the entries of a content type that have field values matching the condition provided in the query parameter. This query is specifically for fields that are part of any block within a Modular Block field.

Example: In the Products content type, we have a Modular Group field named Additional Info ("uid":"additional_info") that contains the Deals ("uid":"deals") block. And, within this Deals block, we have a field named Deal Name ("uid":"deal_name"). If, for instance, you want to retrieve the entries where Deal Name starts with ‘Christmas Deal', use the following value in the query parameter:

{ "additional_info.deals.deal_name": { "$regex": "^Christmas Deal" }}

Search by Regex Within Modular Blocks

Try

AND Operator

Get entries that satisfy all the conditions provided in the '$and' query.

Example: Let’s say you want to retrieve entries in which the Title field is set to 'Redmi Note 3' and the Color field is 'Gold'. The query to be used for such a case would be:

{"$and":[{"title": "Redmi Note 3"},{"color": "Gold"}]}

The response will contain the entries where the values for Title is 'Redmi Note 3' and Color is 'Gold'.

AND operator

Try

AND Operator Within Group

Get entries that satisfy all the conditions provided in the $and query. This query is specifically for fields that are part of the Group field.

Example: In the Products content type, we have a Group field named Bank Offers ("uid":"bank_offers"). And, within this Group field, we have fields named Card Type ("uid":"card_type") and Discount in Percentage ("uid":"discount_in_percentage"). If, for instance, you want to retrieve the entries in where the value for Card Type is ‘Credit Card’ and ‘Discount in Percentage’ is '12', use the following value in the query parameter:

{"$and":[{"bank_offers.card_type": "Credit Card"},{"bank_offers.discount_in_percentage": 12}]}

AND Operator Within Group

Try

AND Operator Within Modular Blocks

Get entries that satisfy all the conditions provided in the $and query. This query is specifically for fields that are part of any block within a Modular Block field.

Example: In the Products content type, we have a Modular Group field named Additional Info ("uid":"additional_info") that contains the Deals ("uid":"deals") and Rating ("uid":"rating") blocks. And, within the Deals and Rating blocks, we have the Deal Name ("uid":"deal_name") and Stars ("uid":"stars") fields, respectively. If, for instance, you want to retrieve the entries in where the values for Deals and Ratings fields are ‘Christmas Deal’ and '2', respectively, use the following value in the query parameter:

{"$and":[{"additional_info.deals.deal_name": "Christmas Deal"},{"additional_info.rating.stars": 2}]}

AND Operator Within Modular Blocks

Try

OR Operator

Get all entries that satisfy at least one of the given conditions provided in the '$or' query.

Example: Let’s say you want to retrieve entries in which either the value for the Color field is 'Gold' or 'Black'. The query to be used for such a case would be:

{ "$or": [{ "color": "Gold" }, { "color": "Black" }] }

The response will contain the entries that have their Color fields set to either 'Gold' or 'Black'.

OR Operator

Try

OR Operator Within Group

Get all entries that satisfy at least one of the given conditions provided in the $or query. This query is specifically for fields that are part of the Group field.

Example: In the Products content type, we have a Group field named Bank Offers ("uid":"bank_offers"). And, within this Group field, we have fields named Card Type ("uid":"card_type") and Discount in Percentage ("uid":"discount_in_percentage"). If, for instance, you want to retrieve the entries where either the value for Card Type is ‘Debit Card’ or the value for Discount in Percentage is '12', use the following value in the query parameter:

{ "$or": [{ "bank_offers.card_type": "Debit Card" }, { "bank_offers.discount_in_percentage": 12}]}

OR Operator Within Group

Try

OR Operator Within Modular Blocks

Get all entries that satisfy at least one of the given conditions provided in the '$or' query. This query is specifically for fields that are part of any block within a Modular Block field.

Example: In the ‘Products’ content type, we have a Modular Group field named ‘Additional Info’ ("uid":"additional_info") that contains the Deals ("uid":"deals") and Rating ("uid":"rating") blocks. And, within the Deals and Rating blocks, we have the Deal Name ("uid":"deal_name") and Stars ("uid":"stars") fields, respectively. If, for instance, you want to retrieve the entries where either the value for Deal Name is ‘Christmas Deal’ or the value for Stars is '2', respectively, use the following value in the query parameter:

{"$or":[{"additional_info.deals.deal_name": "Christmas Deal"},{"additional_info.rating.stars": 2}]}

OR Operator Within Modular Blocks

Try

Less Than

Get entries in which the value of a field is lesser than the value provided in the condition.

Example: Let’s say you want to retrieve all the entries that have value of the Price in USD field set to a value that is less than but not equal to 600. You can send the parameter as:

{ "price_in_usd": { "$lt": 600 } }

This will give you all the entries of mobile phones costing less than but not equal to $600.

Let’s consider another example. You want to retrieve all the entries that have their start date before 8th December, 2017. Now, you need to set this parameter with the date in the ISO Date format as below:

{ "start_date": { "$lt": "2017-12-08T00:00:00.000Z" } }

This will give you all the entries where the start date is before 8th December, 2017, but you will not get the entries of the same date.

Less Than

Try

Less Than Operator Within Group

Get entries in which the value of a field is lesser than the value provided in the condition. This query is specifically for fields that are part of the Group field.

Example: In the Products content type, we have a Group field named Bank Offers ("uid":"bank_offers"). And, within this Group field, we have a subfield named Discount in Percentage ("uid":"discount_in_percentage"). If, for instance, you want to retrieve the entries in which the values for the Discount in Percentage field is less than ‘25’, use the following value in the query parameter:

{ "bank_offers.discount_in_percentage": { "$lt": 25 } }

Less Than Within Group

Try

Less Than Operator Within Modular Blocks

Get entries in which the value of a field is lesser than the value provided in the condition. This query is specifically for fields that are part of any block within a Modular Block field.

Example: In the Products content type, we have a Modular Group field named Additional Info ("uid":"additional_info") that contains the Rating ("uid":"rating") block. And, within this Block field, we have a field named Stars ("uid":"stars"). If, for instance, you want to retrieve the entries in which the values for the Stars field is less than ‘3’, use the following value in the query parameter:

{ "additional_info.rating.stars": { "$lt": 3 } }

Less Than Operator Within Modular Blocks

Try

Less Than Or Equal To

Get entries in which the value of a field is lesser than or equal to the value provided in the condition.

Example: Let’s say you want to retrieve all the entries that have value of the Price in USD field set to a value that is less than or equal to 146. To achieve this, send the parameter as:

{ "price_in_usd": { "$lte": 146 } }

This will give you all the entries of mobile phones costing less than and equal to $600.

Let’s consider another example. If you want to retrieve all the entries that have their start date before and on 8th December, 2017. Now, you need to set this parameter with the date in the ISO Date format as below:

{ "start_date": { "$lte": "2017-11-08T00:00:00.000Z" } }

This will give you all the entries before 8th December, 2017, along with the entries of 8th December, 2017.

Less Than or Equal To

Try

Less Than Or Equal To Operator Within Group

Get entries in which the value of a field is lesser than or equal to the value provided in the condition. This query is specifically for fields that are part of the Group field.

Example: In the Products content type, we have a Group field named Bank Offers ("uid":"bank_offers"). And, within this Group field, we have a subfield named Discount in Percentage ("uid":"discount_in_percentage"). If, for instance, you want to retrieve the entries in which the values for the Discount in Percentage field is less than or equal to ‘25’, use the following value in the query parameter:

{ "bank_offers.discount_in_percentage": { "$lte": 25 } }

Less Than Or Equal To Within Group

Try

Less Than Or Equal To Operator Within Modular Blocks

Get entries in which the value of a field is lesser than or equal to the value provided in the condition. This query is specifically for fields that are part of any block within a Modular Block field.

Example: In the Products content type, we have a Modular Group field named Additional Info ("uid":"additional_info") that contains the Rating ("uid":"rating") block. And, within this Rating block, we have a field named Stars ("uid":"stars"). If, for instance, you want to retrieve the entries in which the values for the Stars field is less than or equal to ‘3’, use the following value in the query parameter:

{ "additional_info.rating.stars": { "$lte": 3 } }

Less Than Or Equal To Operator Within Modular Blocks

Try

Greater Than

Get entries in which the value for a field is greater than the value provided in the condition.

Example: Let’s say you want to retrieve all the entries that have value of the Price in USD field set to a value that is greater than but not equal to 146. You can send the parameter as:

{ "price_in_usd": { "$gt": 146 } }

This will give you all the entries of mobile phones costing greater than and not equal to $146.

Let’s consider another example. If you want to retrieve all the entries that have their start date later than 8th December, 2017. Now, you need to set this parameter with the date in the ISO Date format as below:

{ "start_date": { "$gt": "2017-11-08T00:00:00.000Z" } }

This will give you all the entries after 8th December, 2017.

Greater Than

Try

Greater Than Operator Within Group

Get entries in which the value for a field is greater than the value provided in the condition. This query is specifically for fields that are part of the Group field.

Example: In the Products content type, we have a Group field named Bank Offers ("uid":"bank_offers"). And, within this Group field, we have a subfield named Discount in Percentage ("uid":"discount_in_percentage"). If, for instance, you want to retrieve the entries in which the values for the Discount in Percentage field is greater than ‘25’, use the following value in the query parameter:

{ "bank_offers.discount_in_percentage": { "$gt": 25 } }

Greater Than Within Group

Try

Greater Than Operator Within Modular Blocks

Get entries in which the value for a field is greater than the value provided in the condition. This query is specifically for fields that are part of any block within a Modular Block field.

Example: In the Products content type, we have a Modular Group field named Additional Info ("uid":"additional_info") that contains the Rating ("uid":"rating") block. And, within this Block field, we have a field named Stars ("uid":"stars"). If, for instance, you want to retrieve the entries in which the values for the Stars field is greater than ‘3’, use the following value in the query parameter:

{"additional_info.rating.stars": {"$gt": 3}}

Greater Than Operator Within Modular Blocks

Try

Greater Than Or Equal To

Get entries in which the value of a field is greater than or equal to the value provided in the condition.

Example: Let’s say you want to retrieve all the entries that have value of the Price in USD field set to a value that is less than and equal to 146. You can send the parameter as:

{ "price_in_usd": { "$gte": 146 } }

This will give you all the entries of mobile phones costing greater than and equal to $146.

Let’s consider another example. You want to retrieve all the entries that have their start date 8th December, 2017, and later. Now, you need to set this parameter with the date in the ISO Date format as below:

{ "start_date": { "$gte": "2017-11-08T00:00:00.000Z" } }

This will give you all the entries where the start date falls after 8th December, 2017, along with the entries of the same date.

Greater Than or Equal To

Try

Greater Than Or Equal To Operator Within Group

Get entries in which the value of a field is greater than or equal to the value provided in the condition. This query is specifically for fields that are part of the Group field.

Example: In the Products content type, we have a Group field named Bank Offers ("uid":"bank_offers"). And, within this Group field, we have a subfield named Discount in Percentage ("uid":"discount_in_percentage"). If, for instance, you want to retrieve the entries in which the values for the Discount in Percentage field is greater than or equal to ‘25’, use the following value in the query parameter:

{"bank_offers.discount_in_percentage": { "$gte": 25 } }

Greater Than Or Equal To Within Group

Try

Greater Than Or Equal To Operator Within Modular Blocks

Get entries in which the value of a field is greater than or equal to the value provided in the condition. This query is specifically for fields that are part of any block within a Modular Block field.

Example: In the Products content type, we have a Modular Group field named Additional Info ("uid":"additional_info") that contains the Rating ("uid":"rating") block. And, within this Rating block, we have a field named Stars' ("uid":"stars"). If, for instance, you want to retrieve the entries in which the values for the Stars field is greater than or equal to ‘3’, use the following value in the query parameter:

{"additional_info.rating.stars": {"$gte": 3}

Greater Than Or Equal To Operator Within Modular Blocks

Try

Limit

The limit parameter will return a specific number of entries in the output. So for example, if the content type contains more than 100 entries and you wish to fetch only the first 2 entries, you need to specify '2' as value in this parameter.

Example:

https://cdn.contentstack.io/v3/content_types/product/entries?limit=2

Limit

Try

Skip

The skip parameter will skip a specific number of entries in the output. So, for example, if the content type contains around 12 entries and you want to skip the first 2 entries to get only the last 10 in the response body, you need to specify ‘2’ here.

Example: 

https://cdn.contentstack.io/v3/content_types/product/entries?skip=2

Skip

Try

Order by asc

When fetching entries, you can sort them in the ascending order with respect to the value of a specific field in the response body.

Example: In the Product content type, if you wish to sort the entries with respect to their prices, the parameter can be used as:

https://cdn.contentstack.io/v3/content_types/product/entries?asc=price_in_usd

This will give you all the entries sorted in the ascending order with respect to the Price in USD field.

Order by asc

Try

Order by asc Operator Within Group

Sort your fetched entries in the ascending order with respect to the value of a specific field in the response body. This query is specifically for fields that are part of the Group field.

Example: In the Products content type, we have a Group field named Bank Offers ("uid":"bank_offers"). And, within this Group field, we have a subfield named Discount in Percentage ("uid":"discount_in_percentage"). If, for instance, you want to retrieve entries in the ascending order with respect to the Discount in Percentage field, use the following URL:

https://cdn.contentstack.io/v3/content_types/product/entries?asc=bank_offers.discount_in_percentage

Order by asc Operator Within Group

Try

Order by asc Operator Within Modular Blocks

Sort your fetched entries in the ascending order with respect to the value of a specific field in the response body. This query is specifically for fields that are part of any block within a Modular Block field.

Note: Currently, this query is not applicable for Reference fields within Modular Blocks.

Example: In the Products content type, we have a Modular Group field named Additional Info ("uid":"additional_info") that contains the Rating ("uid":"rating") block. And, within this Block field, we have a field named Stars ("uid":"stars"). If, for instance, you want to retrieve entries in the ascending order with respect to the Stars field, use the following URL:

<a href="https://cdn.contentstack.io/v3/content_types/product/entries?asc=additional_info.rating.stars">https://cdn.contentstack.io/v3/content_types/produ...</a>

Order by asc Operator Within Modular Blocks

Try

Order by desc

When fetching entries, you can sort them in the descending order with respect to the value of a specific field in the response body.

Example: In the Product content type, if you wish to sort the entries with respect to their prices, the parameter can be used as:

https://cdn.contentstack.io/v3/content_types/product/entries?desc=price_in_usd

This will give you all the entries sorted in the descending order with respect to the Price in USD field.

Order by desc

Try

Order by desc Operator Within Group

Sort your fetched entries in the descending order with respect to the value of a specific field in the response body. This query is specifically for fields that are part of the Group field.

Example: In the Products content type, we have a Group field named Bank Offers ("uid":"bank_offers"). And, within this Group field, we have a subfield named Discount in Percentage ("uid":"discount_in_percentage"). If, for instance, you want to retrieve entries in the descending order with respect to the values of the Discount in Percentage field, use the following URL:

https://cdn.contentstack.io/v3/content_types/product/entries?desc=bank_offers.discount_in_percentage

Order By desc Within Group

Try

Order by desc Operator Within Modular Blocks

Sort your fetched entries in the descending order with respect to the value of a specific field in the response body. This query is specifically for fields that are part of any block within a Modular Block field.

Note: Currently, this query is not applicable for Reference fields within Modular Blocks.

Example: In the Products content type, we have a Modular Group field named Additional Info ("uid":"additional_info") that contains the Rating ("uid":"rating") block. And, within this Rating block, we have a field named Stars ("uid":"stars"). If, for instance, you want to retrieve entries in the descending order with respect to the values of the Stars field, use the following URL:

https://cdn.contentstack.io/v3/content_types/product/entries?desc=additional_info.rating.stars

Order by desc Operator Within Modular Blocks

Try

Exists

Get entries if value of the field, mentioned in the condition, exists.

Example: In the Product content type, we have a field named Price in USD. Now, you want to retrieve all the entries in the content type in which the field exists. You can send the parameter as:

{ "price_in_usd": { "$exists": true } }.

Exists

Try

Exists Operator Within Group

Get entries if value of the field, mentioned in the condition, exists. This query is specifically for fields that are part of the Group field.

Example: In the Products content type, we have a Group field named Bank Offers ("uid":"bank_offers"). And, within this Group field, we have a subfield named Card Type ("uid":"card_type"). If, for instance, you want to retrieve the entries in which the values for the Discount in Percentage field exists, use the following value in the query parameter:

{"bank_offers.discount_in_percentage": { "$exists": true }}

Exists Within Group

Try

Exists Operator Within Modular Blocks

Get entries if value of the field, mentioned in the condition, exists. This query is specifically for fields that are part of any block within a Modular Block field.

Example: In the Products content type, we have a Modular Group field named Additional Info ("uid":"additional_info") that contains the Deals ("uid":"deals") block. And, within this Block field, we have a field named Deal Name ("uid":"deal_name"). If, for instance, you want to retrieve the entries in which the values for the Stars field exists, use the following value in the query parameter:

{"additional_info.rating.stars": {"$exists": true }}

Exists Operator Within Modular Blocks

Try

Only Operator

The only[][] parameter will include the data of only the specified fields for each entry and exclude the data of all other fields. There are two approaches to this parameter. Firstly, we have the only[BASE][] parameter, where 'BASE' is the default value and refers to the top-level fields of the schema. Secondly, we have the only[Reference_field_uid][] parameter, where you need to enter the UID of the reference field in place of "Reference_field_uid".

Example: In the Product content type, if we need to retrieve the data of only the Price in USD parameter of all the entries, you can send the parameter as:

https://cdn.contentstack.io/v3/content_types/author/entries?only[BASE][]=price_in_usd

Only operator

Try

Only Operator Within Group

Get entries in which the data of a specific field is included in the response JSON. This query is specifically for fields that are part of the Group field.

Example: In the Products’ content type, we have a Group field named Bank Offers ("uid":"bank_offers"). And, within this Group field, we have a subfield named Discount in Percentage ("uid":"discount_in_percentage"). If, for instance, you want to retrieve only the values of the Discount in Percentage field of all the entries, you can send the parameters as:

https://cdn.contentstack.io/v3/content_types/product/entries?only[BASE][]=bank_offers.discount_in_percentage

Only Operator Within Group

Try

Only Operator Within Modular Blocks

Get entries in which the data of a specific field is included in the response JSON. This query is specifically for fields that are part of any block within a Modular Block field.

Example: In the Products content type, we have a Modular Group field named Additional Info ("uid":"additional_info") that contains the Deals ("uid":"deals") block. And, within this Deals block, we have a field named Stars ("uid":"stars"). If, for instance, you want to retrieve the values of all the Stars field from all the entries, you can send the parameters as:

https://cdn.contentstack.io/v3/content_types/product/entries?only[BASE][]=additional_info.rating.stars

Only Operator Within Modular Blocks

Try

Exclude Operator

The except[][] parameter will exclude the data of the specified fields for each entry and will include the data of the rest of the fields. There are two approaches to this parameter. Firstly, we have the except[BASE][] parameter, where 'BASE' is the default value and refers to the top-level fields of the schema. Secondly, we have the except[Reference_field_uid][] parameter, where you need to enter the UID of the reference field in place of Reference_field_uid.

Example: In the Product content type, if we need to retrieve the data of entries of all the other fields except the Price in USD parameter, you can send the parameter as:

https://cdn.contentstack.io/v3/content_types/product/entries?except[BASE][]=price_in_usd

Exclude operator

Try

Exclude Operator Within Group

Get entries in which the data of a specific field is excluded from the response JSON, but the data of the rest of the fields are included. This query is specifically for fields that are part of the Group field.

Example: In the Products content type, we have a Group field named Bank Offers ("uid":"bank_offers"). And, within this Group field, we have a subfield named Discount in Percentage ("uid":"discount_in_percentage"). If, for instance, you want to retrieve all the entries of a content type, but exclude the data for the Discount in Percentage field in the JSON response, you can send the parameters as:

https://cdn.contentstack.io/v3/content_types/product/entries?except[BASE][]=bank_offers.discount_in_percentage

Exclude Operator Within Group

Try

Exclude Operator Within Modular Blocks

Get entries in which the data of a specific field is excluded from the response JSON, but the data of the rest of the fields are included. This query is specifically for fields that are part of any block within a Modular Block field.

Example: In the Products content type, we have a Modular Group field named Additional Info ("uid":"additional_info") that contains the Deals ("uid":"deals") block. And, within this Block field, we have a field named Stars ("uid":"stars"). If, for instance, you want to retrieve all the entries of a content type, but exclude the data for the Stars field in the JSON response, you can send the parameters as:

https://cdn.contentstack.io/v3/content_types/product/entries?except[BASE][]=additional_info.rating.stars

Exclude Operator Within Modular Blocks

Try

Count

The include_count function returns the number of entries for a specified content type.

Example: If you wish to know the total number of entries in the Product content type, you need to run the following command:

https://cdn.contentstack.io/v3/content_types/product/entries?environment={environment}&include_count=true

Count

Try

Pagination

The 'Get all entries' API request returns only the first 100 entries of the specified content type. Similarly, the 'Get all assets' request fetches the first 100 assets of a particular stack.

In both requests, first, use the include_count parameter to get the total count of the items (entries/assets). Learn more about the Count parameter.

Since only 100 items are returned at a time in your response (in case of both requests), you can get the rest of the items in batches using the skip parameter in subsequent requests. Learn more about the Skip parameter.

You can paginate the output of a request by using the limit parameter. For example, if your have 200 entries and/or assets and you want to retrieve them all but display only 10 items at a time. Use the limit=10 and skip=10 parameters, to get them all but display only 10 items per page.

The syntax of the pagination request will look like the following:

• For entries: https://cdn.contentstack.io/v3/content_types/product/entries?environment={environment}&locale={locale}&include_count=true&skip={skip_value}&limit={limit_value}
• For assets: https://cdn.contentstack.io/v3/assets?environment={environment_name}&include_dimension={boolean_value}&include_count=true&skip={skip_value}&limit={limit_value}

Pagination

Try