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 (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
Rate limit is the maximum number of requests you can make using Contentstack’s API in a given period. There are no limits on the requests that you make to Contentstack’s CDN cache. For Content Delivery API requests, i.e., requests to the origin server, we have set a maximum limit of 100 requests per second per organization.
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
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 entryTry
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 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 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.
Initial Synchronization
Initial SyncTry
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.
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:
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.
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 tokenTry
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
.
Subsequent Sync
Subsequent SyncTry
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.
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.
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>
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.
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
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 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
