Content Delivery API
[API VERSION : 3.0.0]Introduction
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 13 POPs in North America, 11 in Asia, 6 in Europe, and 1 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 are private APIs, you will need the API Key and the Access Token of your stack to make requests.
The API Key is a unique key assigned to each stack. The Access Token is a read-only credential that you get after logging into your account. You need to pass the API Key and the Access Token of your stack as HTTP headers to authenticate your request.
To retrieve these values, log in to your Contentstack account and navigate to SETTINGS > STACK. Only the Developers and Stack Owners can view the API key and Access Token of a stack. The Access Token is a read-only token. This means that this token can be used to fetch content only, and not to edit or create new content in your stack.
The API Key and Access Token of a stack are non-editable. You can copy these values by clicking on the ‘click to copy’ icon beside the fields. Users have the provision to reset the Access Token by clicking on the ‘Reset’ button.
Rate Limiting
Rate limit is the maximum number of requests you can make using Built.io Contentstack’s API in a given period. For content delivery, most requests are served via cache (due to CDN), and very few requests are made to the origin server. Hence, there is no maximum limit to number of requests made using the Content Delivery APIs.
API conventions
- The base URL for Content Delivery API is
cdn.contentstack.io. - The API version can be found in the URL, e.g.
cdn.contentstack.io/v3/endpoint. - URL paths, URL query parameter names, and JSON field names are case sensitive.
- URL paths use 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 APIs return standard HTTP error code formats.
- Unexpected query parameters are ignored.
- Unexpected JSON fields in the request body are ignored.
- 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.
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 serves; it is very rare though.
Reference
Stacks
A stack is a space that stores the content of a project (a web or mobile property). Within a stack, you can create content structures, content entries, users, etc. related to the project. Read more about Stacks
Stack
Get a single stackTry
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 typesTry
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 typeTry
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 entriesTry
This 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 of which you wish to get the entries.
You can apply queries to filter assets/entries. Refer to the Queries section for more details.
Single Entry
Get a single entryTry
This call fetches a particular entry of a content type.
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 assetsTry
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 assetTry
This call fetches a specific asset of a particular stack.
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.
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"}
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"}
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 OperatorTry
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"}}
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"}}
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 OperatorTry
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"]}}
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"]}}
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'.
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"]}}
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" ] } }
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 content type 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
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
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
Try
Reference Search Equals
Get entries having values based on referenced fields. This query retrieves all entries that satisfy query conditions made on referenced fields.
Example: In the Product content type, if you wish to retrieve all entries that have their brand title set to Apple Inc. So, the query that needs to be run is given below:
{"brand":{"$in_query":{"title":"Apple Inc."}}}
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”}}}}
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"}}}
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"}}}
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 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 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"}}}
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."}}}
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:
https://cdn.contentstack.io/v3/content_types/content_type_uid/entries?include[]={"bank_offers.bank":{"$nin_query":{"title":"Citigroup"}}}
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:
https://cdn.contentstack.io/v3/content_types/content_type_uid/entries?include[]={"additional_info.related_products.products":{"$nin_query":{"title":"iPhone 7 128GB"}}}
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.
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" } }
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" }}
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'.
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}]}
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}]}
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 OperatorTry
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}]}
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}]}
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 ThanTry
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 } }
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 } }
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 ToTry
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 } }
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 } }
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 ThanTry
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 } }
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}}
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 ToTry
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 } }
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}
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
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
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.
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
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.
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:
https://cdn.contentstack.io/v3/content_types/product/entries?asc=additional_info.rating.stars
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.
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
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.
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
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 } }.
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 }}
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 }}
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
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
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
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
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
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
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
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 list of all the 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.
If the you get more than 100 items 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 the request by using the limit parameter. So, instead of getting all the 100 items at once, use limit=10 to get 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?api_key={api_key}&access_token={access_token}&environment={environment}&locale={locale}&include_count=true&skip={skip_value}&limit={limit_value} - For assets:
https://cdn.contentstack.io/v3/assets?api_key={api_key}&access_token={access_token}&environment={environment_name}&include_dimension={boolean_value}&include_count=true&skip={skip_value}&limit={limit_value}
Try
Include Publish Details
When fetching an entry of a content type, by default, the publish details of the entry are not included in the response. To include the publish details of an entry (also, for assets), you need to pass the include_publish_details parameter with its value set to ‘true’.
Example: In the ‘Product’ content type, to get the details of which version of an entry is published in which environment, you can set the parameter as follows:
{ "include_publish_details": 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. However, if you wish to retrieve the publish details of a single environment, make use of the environment parameter and pass the UID of the environment within it.
The syntax of the call is:
https://cdn.contentstack.io/v3/content_types/{content_type_uid}/entries/{entry_uid}?environment={environment_uid}&locale={locale_uid}&include_publish_details={boolean_value}
Also Read
