Content Delivery API

[API VERSION : 3.0.0]

Introduction

Base URL

For US region: https://cdn.contentstack.io/

For European region: https://eu-cdn.contentstack.com/

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.

Warning: The Content Delivery API (CDA), available at cdn.contentstack.io, should be used to only fetch content from Contentstack. We recommend users to NOT use this endpoint for any other content management activities, because all content management activities using this endpoint will be blocked soon.

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. Our CDN has close to 100 POPs and is adding new ones all the time.

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

Content Delivery SDKs

We have created SDKs, API references, getting started guides, and sample apps for some of the popular languages and platforms. You can use them to build your own apps and fetch content from Contentstack.

Contentstack SDKs let you interact with the Content Delivery APIs and retrieve content from Contentstack. They are read-only in nature. The SDKs fetch and deliver content from the nearest server via Fastly, our powerful and robust CDN.

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

We provide SDKs for the following platforms:

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

Authentication

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

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

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

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

For stacks that are part of organizations created after June 24, 2020:

  • Users will not be able to use Access Tokens to run Content Delivery API (CDA) requests. To make authorized CDA requests, use the value of the delivery token against the access_token key.
  • Users will not be able to use authentication parameters such as api_key (Stack API key), access_token (access token of the stack), authtoken (user generated authtoken), and authorization (management token of the stack) as query parameters for any stack-specific API requests.

Note: We have deprecated the usage of Access Tokens for all stacks. We strongly recommend you to use Delivery Tokens for fetching published content and use Management Tokens for fetching draft content.

How to Get API Key and Delivery Token

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

  1. Go to your stack.
  2. Navigate to Settings > Stack.
  3. On the right-hand side of the page, under API CREDENTIALS, you will get the API Key of your stack.

    Note: Only the developers, admins and stack owners can view the API key.

  4. To get a delivery token or view existing delivery tokens, navigate to Settings > Tokens > Delivery Tokens. From the list, pick the Delivery Token that you want.
    Read more about how you can create a new delivery token.

Note: Only the stack owners, developers, and admin can create delivery tokens.

Rate Limiting

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

API conventions

  • The base URL for Content Delivery API for the US region is cdn.contentstack.io. and  for the European region it is  eu-cdn.contentstack.com
  • The API version (in our case, 'v3') can be found in the URL, e.g. cdn.contentstack.io/v3/endpoint.
  • Only GET verb or methods are recommended on cdn.contentstack.io.
  • URL paths use lower case and all the operations are specified in URL query parameters such as count, include_count, and query.
  • Query parameters are case sensitive and uses lower case, underscore (_) separated words.
  • The success/failure status of an operation is determined by the HTTP status it returns. Additional information is included in the HTTP response body. Read more about it in the HTTP Headers section.

HTTP Headers

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

Here’s what an HTTP response body looks like:

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

Let’s understand what the above HTTP Header means:

  • x-served-by: cache-lax8631-LAX, cache-bur17525-BUR
    Two cache-nodes in X-Served-By show that shielding is turned on, with cache-lax8631-LAX serving as the delivering cache node at the shield datacenter and cache-bur17525-BUR serving as the delivering cache node at the "local" datacenter.
  • < x-cache: MISS, HIT
    The X-Cache: MISS, HIT indicates that the requested object was not in the shield cache (a MISS) but was in the local delivering node (a HIT). For more details, refer Understanding cache HIT and MISS headers with shielded services.
  • < x-cache-hits: 0, 1
    The X-Cache-Hits reflects that same “MISS, HIT” information in numeric format as 0, 1.
  • < x-runtime: 27ms
    The X-Runtime HTTP response header provides the time (in milliseconds) an application takes to process a request.
  • < age: 5182
    Age denotes a non-negative integer that represents the time in seconds the object has been in a proxy cache.
  • < x-timer: S1557441707.643683,VS0,VE0
    The X-Timer header provides the timing information about the journey of a request from end to end.
    The above header can be broken down into three parts, each separated by commas:
    • S1557441707.643683: The first section of the header (starting with S) represents a Unix timestamp of the start of the request on our edges.
    • VS0: The next section, VS or "varnish start," represents the start of the varnish part of the request's journey and will always be 0.
    • VE0: The last section, VE or "varnish end," represents the sum of the length of the trip. For cache HITs, the length of the trip will nearly always be 0 (not actually zero, but less than a millisecond is rounded down).
      For cache MISSs, this number represents the number of milliseconds it took to retrieve the data from your origin server and send the response back to the requester.
      For more information, you can refer to the Understanding the X-Timer header guide.

Errors

If there is something wrong with the API request, Contentstack returns an error.

Contentstack uses conventional, standard HTTP status codes for errors, and returns a JSON body containing details about the error. In general, codes in the 2xx range signify success. The codes in the 4xx range indicate error, mainly due to information provided (for example, a required parameter or field was omitted). Lastly, codes in the 5xx range mean that there is something wrong with Contentstack’s servers; it is very rare though.

Let’s look at the error codes and their meanings.

HTTP status code Description
400 Bad Request The request was incorrect or corrupted.
401 Access Denied The login credentials are invalid.
403 Forbidden Error The page or resource that is being accessed is forbidden.
404 Not Found The requested page or resource could not be found.
412 Pre Condition Failed The entered API key is invalid.
422* Unprocessable Entity (also includes Validation Error and Unknown Field)
The request is syntactically correct but contains semantic errors
429 Rate Limit Exceeded The number of requests exceeds the allowed limit for the given time period. 
500 Internal Server Error The server is malfunctioning and is not specific on what the problem is.
502 Bad Gateway Error A server received an invalid response from another server.
504 Gateway Timeout Error A server did not receive a timely response from another server that it was accessing while attempting to load the web page or fill another request by the browser.

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

Postman Collection

About Contentstack Postman Collection

The Contentstack Postman collection is a set of preconfigured REST API requests that will make it easy for you to get started with the Contentstack APIs and try out our API requests through the popular Postman REST client.

Install Postman

To use the Contentstack Postman collection you will need to have the Postman desktop app installed on your device.

Note: If you have already installed Postman for your device, go to the Download Latest Postman Collection for Contentstack section.

Postman is available for Windows (x32), Windows (x64), Mac, and Linux environments.

Download Latest Collection

Once you have installed Postman for your device, click on the following button to download and install our latest Postman collection that covers all the Content Delivery API endpoints for Contentstack.

Note: The Contentstack Postman collection does not support the now deprecated Postman Chrome extension. Make sure you have installed the latest version of the Postman desktop app.

After selecting the appropriate variant of Postman, the collection will open the Postman app and appear in the left pane:

Collection_appears_on_the_left_pane.png

Download Collection from GitHub Page

We have also hosted our Postman collection on GitHub. You can follow the steps mentioned in the Readme file to download and start using it.

You can also choose to watch the latest Postman collection to get notifications of new releases or updates.

To do so, click on the following Watch button and select Watching.

Configure Environment Variables

When you download and install the latest version of the Content Delivery API (CDA) Postman collection, you also download and import the respective environment along with the environment variables.

Once your environment is imported, next you need to set your Contentstack account specific values.

Note: As these environment variables are referenced across multiple API requests, once you set the variables, it becomes a lot more convenient to make repeated use of the Postman collection.

Some of the important variables that you need to set are as follows:

Environment Variable Value
base_url cdn.contentstack.io
api_key your_stack_api_key
access_token your_environment-specific_delivery_token

Note: The Contentstack Postman collection will require a valid environment-specific Delivery token to make API calls. Check out the Authentication section for more details.

If you want to add your own environment variables, you can follow the procedure in the next section.

Add Other Environment Variables

To add any new environment variables for your Postman collection, perform the following steps:

  1. Identify the environment variables that you want to define.
  2. In the top right corner of Postman, click on the “Manage Environments” settings cog.
    Click on the Manage Environments cog_CDA.png

  3. Click on your environment Content Delivery API - Environment.
  4. In the VARIABLE field, enter the name of the environment variable.
    In the INITIAL VALUE field, enter your Contentstack-account-specific value that will replace the variable when the call is made.
    Manage Environments_CDA.png
  5. Once you have defined your variables, click on Update.

Update Environment Variables

With every new API request added, we update our environment file. So, to get the latest environment variables, you need to download the collection along with the updated environment file again, compare your existing environment with the latest environment, identify and add the new variables to your existing environment.

Next, let’s see how you can run API Requests from your Contentstack Postman collection using your environment.

Make an API Request

With the Contentstack Postman Collection loaded into the Postman app (on the left pane) and the environment created, you can now make API requests to the Contentstack API via Postman.

To make an API request, perform the following steps:

  1. Select the respective environment, Content Delivery API-Environment, from the dropdown.
  2. Select an API Request from the Contentstack Postman Collection. In this example, we will use the Get all content types request which is a part of the Content types folder.

    Note: If you want to make changes to your parameters or want to add parameters of your own, you can do it here.

  3. Next, click on Send at the top right to make the API request.

How_to_make_an_API_Request.png

The API call should return with a response under the Body tab in the bottom half of the screen.

Response Body of Your API Request.png

Working with Queries

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

Querying Entries

You can add queries to extend the functionality of an entry-specific API call. To add a query, you can either append the query parameter directly to the entry URL or append the query parameter along with your conditional query (in JSON format) to the entry URL.

Case 1: Append the query param

If you want to return a specific number of entries in your response output, you can use the limit query parameter. For example, if you want to retrieve only the first 2 entries of a content type, pass '2' as the value for the limit parameter.

https://cdn.contentstack.io/v3/content_types/{content_type_uid}/entries?limit=2

Case 2: Append the conditional query

If you want to retrieve all the entries of a content type in which the value for the Title ("uid":"title") field is “ABC”, you can append the query parameters to the entry URL as follows:

https://cdn.contentstack.io/v3/content_types/{content_type_uid}/entries?query={"title": "ABC"}

Let’s say you want to retrieve all the entries that have their start date as 8th December 2017. Now, you need to append the query with the start date in the ISO Date format as below:

https://cdn.contentstack.io/v3/content_types/{content_type_uid}/entries?query={ "start_date": "2017-12-08T00:00:00.000Z"  }

You can append multiple queries in a single API Request as follows:

{entry_URL}?environment={environment}&locale={locale}&include_count=true&skip={skip_value}&limit={limit_value}

Querying Assets

You can use Image Delivery APIs by appending queries to the image URL:

{image_url}?query_parameter

For example, to resize the width of an image to 100px, you need to append ?width={100} to the image URL. So, the API request would be:

https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/image_name?width=100.

You can also use multiple queries in a single API request as follows:

{image_url}?width={width_value}&height={height_value}&resize-filter={resize-filter_value}

Secure API Keys and Tokens

We strongly advise against storing your API keys and tokens in your collection permanently. If you or someone else shares the collection by mistake, other users will be able to export it along with these keys.

We recommend that you provide your Contentstack account-specific API keys and tokens in your environment or directly to the sample requests.

Postman Collection Updates

We keep our Postman Collection updated. To get the latest version of our Postman Collection, all you need to do is to download the Postman Collection along with the updated environment again and you are good to go.

You can also choose to watch for the latest Postman Collection updates on our GitHub repository and get notifications of new releases or updates to the repository. The GitHub Readme doc will help you with the steps that you need to follow.

Reference

Content Types

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

All Content Types

Get all content types

Try

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

When executing the API call, you can add queries to extend the functionality of this API call.

Tip: If any of your content types contains a Global field and you wish to fetch the content schema of the Global field, then you need to pass theinclude_global_field_schema:true parameter. This parameter helps return the Global field's schema along with the content type schema.

To query your content types, under the 'URI Parameters' section, insert a parameter named query and provide the query in JSON format as the value. To learn more about the queries, refer to the Queries section of the Content Delivery API doc.

Note: This API request will return a maximum of 100 content types. To retrieve the next batch of content types, make use of the skip parameter (or refer Pagination for more details).

Single Content Type

Get a single content type

Try

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

Global Fields

A Global field is a reusable field (or group of fields) that you can define once and reuse in any content type within your stack. This eliminates the need (and thereby time and efforts) to create the same set of fields repeatedly in multiple content types. Read more about Global fields.

All Global Fields

Get all global fields

Try

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

Single Global Field

Get a single global field

Try

This request allows you to fetch comprehensive details of a specific global field.

When executing the API call, in the 'URI Parameters' section, provide the unique ID of your global field.

Entries

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

All Entries

Get all entries

Try

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

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

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

Using Delivery Tokens

  • Fetches only published content
  • Environment parameter in the query is mandatory
    • Fetches content of entry/entries published of the specified environment
  • Version is optional
    • When no version is specified, it fetches the latest published version
    • If a version is specified which is not the latest published version, it will not return any result
  • Locale is optional
    • When no locale is specified, it returns the entry from the master locale
    • Specify a locale in the query to get entry/entries of a particular locale

Using Access Token

  • Fetches published content
  • Environment is mandatory
    • Fetches content of entry/entries published on the specified environment.
  • Version is optional
    • When no version is specified, it returns the latest version
    • To retrieve a specific version, specify the version number under this parameter. In such a case, DO NOT specify any environment.
  • Locale is optional
    • When no locale is specified, it returns the entry from the master locale
    • Specify a locale to get entry/entries of only a particular locale

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

Single Entry

Get a single entry

Try

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

Using Delivery Tokens

  • Fetches only published content
  • Environment parameter in the query is mandatory
    • Fetches content of entry/entries published of the specified environment
  • Version is optional.
    • When no version is specified, it fetches the latest published version
    • If a version is specified which is not the latest published version, it will not return any result
  • Locale is optional
    • When no locale is specified, it returns the entry from the master locale
    • Specify a locale in the query to get entry/entries of a particular locale

Using Access Token

  • Fetches published content
  • Environment is mandatory 
    • Fetches content of entry/entries published on the specified environment.
  • Version is optional
    • When no version is specified, it returns the latest version
    • To retrieve a specific version, specify the version number under this parameter. In such a case, DO NOT specify any environment.
  • Locale is optional
    • When no locale is specified, it returns the entry from the master locale
    • Specify a locale to get entry/entries of only a particular locale

Assets

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

All Assets

Get all assets

Try

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

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

Single Asset

Get a single asset

Try

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

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

Synchronization

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

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

Initial Synchronization

Initial Sync

Try

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

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

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

Applicable parameters:

Parameter Values
content_type_uid Enter content type UID. e.g., products
This retrieves published entries of specified content type.
locale Enter locale code. e.g., en-us
This retrieves published entries of specific locale.
start_from Enter the start date. e.g., 2018-08-14T00:00:00.000Z
This retrieves published entries starting from a specific date.
type Applicable values are:
  • entry_published
  • asset_published
  • entry_unpublished
  • asset_unpublished
  • entry_deleted
  • asset_deleted
  • content_type_deleted

If you do not specify any value, it will bring all published entries and published assets. You can pass multiple types as comma-separated values, for example, entry_published,entry_unpublished,asset_published.

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

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

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

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

Sync using pagination token

Sync using pagination token

Try

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

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

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

Subsequent Sync

Subsequent Sync

Try

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

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

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

Queries

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

Equals Operator

Equals Operator

Try

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

This query will work for both entries as well as assets.

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

{"title": "Redmi 3S"}

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

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

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

Equals Operator Within Group
Equals Operator Within Group

Try

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.

This query will work for entries only.

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

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

Equals Operator Within Modular Blocks
Equals Operator Within Modular Blocks

Try

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.

This query will work for entries only.

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"}

Not-equals Operator

Not-equals Operator

Try

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

This query will work for both entries as well as assets.

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

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

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

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

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

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

Not-equals Operator Within Group
Not-equals Operator Within Group

Try

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.

This query will work for entries only.

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

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

Not-equals Operator Within Modular Blocks
Not-equals Operator Within Modular Blocks

Try

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.

This query will work for entries only.

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"}}

Array Equals Operator

Array Equals Operator

Try

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.

This query will work for entries only.

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

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

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

Array Equals Operator Within Group
Array Equals Operator Within Group

Try

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.

This query will work for entries only.

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

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

Array Equals Operator Within Modular Blocks
Array Equals Operator Within Modular Blocks

Try

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.

This query will work for entries only.

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

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

Array Not-equals Operator

Array Not-equals Operator

Try

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.

This query will work for entries only.

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

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

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

Array Not-equals Operator Within Group
Array Not-equals Operator Within Group

Try

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.

This query will work for entries only.

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

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

Array Not-equals Operator Within Modular Blocks
Array Not-equals Operator Within Modular Blocks

Try

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.

This query will work for entries only.

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" ] } }

Include Reference

Include Reference

Try

When fetching an entry, the content of referred entries that are part of the parent entry is NOT included in the Response body; you only get their UIDs. To include the content of the referred entries in your response, you need to use the include[] parameter and specify the UID of the reference field as value.

The API request should be as follows:

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

This query will work for entries only.

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

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

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

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

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

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

Include Reference Within Group
Include Reference Within Group

Try

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.

This query will work for entries only.

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

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

Include Reference 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.

This query will work for entries only.

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 as follows:

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

Include Reference Within Modular Blocks
Include Reference Within Modular Blocks

Try

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.

This query will work for entries only.

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

Reference Search Equals

Reference Search Equals

Try

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

This query will work for entries only.

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

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

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

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

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

  • General query: {"reference_field_uid":{"$in_query":{"referred_content_type's_field_uid":{"query_to_be_applied"}}}}
  • Multiple content type reference query: {"reference_field_uid":{"$in_query":{"referred_content_type's_field_uid":{"query_to_be_applied"}}}, "_content_type_uid":"UID_of_referred_content_type"}

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

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

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

  • General query: {"referred_parent_content_type_field_uid": {"$in_query": {"referred_content_type_2_field_uid": { "$in_query": {"title": "Sample"}}}}}
  • Multiple content type reference query: {"referred_parent_content_type_field_uid": {"$in_query": {"referred_content_type_2_field_uid": { "$in_query": {"title": "Sample", "_content_type_uid": "referred_content_type_3_uid"} }, "_content_type_uid": "referred_content_type_2_uid"}, "_content_type_uid": "referred_parent_content_type_uid"}}
Reference Search Equals for Nested Querying

You can use queries within this query (nested querying) in order to to query on the referred entries.

This query will work for entries only.

The syntax of the query will be as follows:

  • General query: {"reference_field_uid": { "$in_query": { "referred_fieldname": {"query_to_be_applied"}}}}
  • Multiple content type referencing query: {"reference_field_uid": { "$in_query": { "referred_fieldname": {"query_to_be_applied"}}, "_content_type_uid ":"UID_of_parent_content_type"}}

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

  • General query: {"brand": {"$in_query": {"title": {"$regex": "^/a", "$options": "i"}}}}
  • Multiple content type referencing query: {"brand": {"$in_query": {"title": {"$regex": "^/a", "$options": "i"}, "_content_type_uid": "UID_of_referred_content_type"}, "_content_type_uid": "UID_of_parent_content_type"}}

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

Reference Search Equals Within Group
Reference Search Equals Within Group

Try

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:

  • General query: {"bank_offers.bank": {"$in_query": { "title": "Citigroup"}}}
  • Multiple content type referencing query: { "bank_offers.bank": { "$in_query": { "title": "Citigroup", "_content_type_uid": "UID_of_referred_content_type" }, "_content_type_uid": "UID_of_parent_content_type" } }
Reference Search Equals Within Modular Blocks
Reference Search Equals Within Modular Blocks

Try

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

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

Note that this query will work for entries only.

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:

  • General query: {"additional_info.related_products.products": {"$in_query": { "title": "iPhone 7 128GB"}}}
  • Multiple content type referencing query: {"additional_info.related_products.products": {"$in_query": { "title": "iPhone 7 128GB", "_content_type_uid": "UID_of_referred_content_type"}, "_content_type_uid": "UID_of_parent_content_type"}}

Reference Search Not-equals

Reference Search Not-equals

Try

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.

Note that this query will work for entries only.

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:

  • General query: {"brand": {"$nin_query": {"title": "Apple Inc."}}}
  • Multiple content type referencing query: { "brand": {"$nin_query": {"title": "Apple Inc.", "_content_type_uid": "UID_of_referred_content_type"}, "_content_type_uid": "UID_of_parent_content_type"}}

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

Reference Search Not-equals Within Group
Reference Search Not-equals Within Group

Try

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.

Note that this query will work for entries only.

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.

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:

  • General query: {"bank_offers.bank": {"$nin_query": {"title": "Citigroup"}}}
  • Multiple content type query: {"bank_offers.bank": {"$nin_query": {"title": "Citigroup", "_content_type_uid": "UID_of_referred_content_type"}, "_content_type_uid": "UID_of_parent_content_type"}}
Reference Search Not-equals Within Modular Blocks
Reference Search Not-equals Within Modular Blocks

Try

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.

Note that this query will work for entries only.

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.

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:

  • General query: { "additional_info.related_products.products": {"$nin_query": {"title": "iPhone 7 128GB"}}}
  • Multiple content type referencing query: { "additional_info.related_products.products": {"$nin_query": {"title": "iPhone 7 128GB", "_content_type_uid": "UID_of_referred_content_type"}, "_content_type_uid": "UID_of_parent_content_type"}}

Search by Regex

Search by Regex

Try

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.

This query will work for both entries as well as assets.

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 'Bl'. You can use the parameter as:

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

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

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

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

Search by Regex Within Group
Search By Regex Within Group

Try

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.

Note: 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 starts with “Credit Card,” use the following value in the query parameter:

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

Search by Regex Within Modular Blocks
Search by Regex Within Modular Blocks

Try

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 will work for entries only and works 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" }}

AND Operator

AND operator

Try

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

This query will work for both entries as well as assets.

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

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

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

AND Operator Within Group
AND Operator Within Group

Try

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

This query is specifically for entries and works on fields that are part of the Group field.

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

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

AND Operator Within Modular Blocks
AND Operator Within Modular Blocks

Try

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

This query is specifically for entries and works on 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}]}

OR Operator

OR Operator

Try

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

This query will work for both entries as well as assets.

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

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

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

OR Operator Within Group
OR Operator Within Group

Try

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

This query is specifically for entries and works for fields that are part of the Group field.

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

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

OR Operator Within Modular Blocks
OR Operator Within Modular Blocks

Try

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

This query is specifically for entries and works on 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}]}

Less Than

Less Than

Try

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

This query will work for both entries as well as assets.

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

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

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

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

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

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

Less Than Operator Within Group
Less Than Within Group

Try

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

This query is specifically for fields that are part of the Group field.

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

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

Less Than Operator Within Modular Blocks
Less Than Operator Within Modular Blocks

Try

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

This query is specifically for fields that are part of any block within a Modular Block field.

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

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

Less Than Or Equal To

Less Than or Equal To

Try

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

This query will work for both entries as well as assets.

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 $146.

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

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

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

Less Than Or Equal To Operator Within Group
Less Than Or Equal To Within Group

Try

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

This query is specifically for fields that are part of the Group field.

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

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

Less Than Or Equal To Operator Within Modular Blocks
Less Than Or Equal To Operator Within Modular Blocks

Try

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 entries and works on 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 } }

Greater Than

Greater Than

Try

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

This query will work for both entries as well as assets.

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

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

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

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

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

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

Greater Than Operator Within Group
Greater Than Within Group

Try

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

This query is specifically for entries and works on fields that are part of the Group field.

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

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

Greater Than Operator Within Modular Blocks
Greater Than Operator Within Modular Blocks

Try

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

This query is specifically for entries and works on fields that are part of any block within a Modular Block field.

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

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

Greater Than Or Equal To

Greater Than or Equal To

Try

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

This query will work for both entries as well as assets.

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

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

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

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

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

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

Greater Than Or Equal To Operator Within Group
Greater Than Or Equal To Within Group

Try

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

This query is specifically for fields that are part of the Group field.

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

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

Greater Than Or Equal To Operator Within Modular Blocks
Greater Than Or Equal To Operator Within Modular Blocks

Try

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}

Limit

Limit

Try

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.

This query will work for both entries as well as assets.

Example:

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

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.

This query will work for both entries as well as assets.

Example:

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

Order by asc

Order by asc

Try

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

This query will work for both entries as well as assets.

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?environment=production&asc=price_in_usd

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

Order by asc Operator Within Group
Order by asc Operator Within Group

Try

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 entries and works on 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?environment=production&asc=bank_offers.discount_in_percentage

Order by desc

Order by desc

Try

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

This query will work for both entries as well as assets.

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?environment=production&desc=price_in_usd

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

Order by desc Operator Within Group
Order By desc Within Group

Try

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 entries and works on 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?environment=production&desc=bank_offers.discount_in_percentage

Order by desc Operator Within Modular Blocks
Order by desc Operator Within Modular Blocks

Try

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 entries and works on 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?environment=production&desc=additional_info.rating.stars

Exists

Exists

Try

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

This query will work for entries only.

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

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

Exists Operator Within Group
Exists Within Group

Try

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

This query is specifically for entries and work on fields that are part of the Group field.

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

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

Exists Operator Within Modular Blocks
Exists Operator Within Modular Blocks

Try

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

This query is specifically for entries and works on 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 }}

Only Operator

Only operator

Try

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

This query will work for entries only.

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?environment=production&only[BASE][]=price_in_usd

Only Operator Within Group
Only Operator Within Group

Try

Get entries in which the data of a specific field is included in the response JSON.

This query is specifically for entries and works on 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?environment=production&only[BASE][]=bank_offers.discount_in_percentage

Only Operator Within Modular Blocks
Only Operator Within Modular Blocks

Try

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?environment=production&only[BASE][]=additional_info.rating.stars

Exclude Operator

Exclude operator

Try

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.

This query will work for entries only.

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?environment=production&except[BASE][]=price_in_usd

Exclude Operator Within Group
Exclude Operator Within Group

Try

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 entries and works with 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?environment=production&except[BASE][]=bank_offers.discount_in_percentage

Exclude Operator Within Modular Blocks
Exclude Operator Within Modular Blocks

Try

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 entries and works with 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?environment=production&except[BASE][]=additional_info.rating.stars

Count

Count

Try

To retrieve the count of entries, we have two parameters: include_count (retrieves entries' details and their count) and count (retrieves only the count of entries).

This query will work for both entries as well as assets.

Example: If you wish to know the total number of entries in the Product content type and also retrieve all the data, you need to run the following API request:

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

To get only the count, run the following API request:

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

Pagination

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

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

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

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

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

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

All Query Parameters

The table below contains the list of all query parameters used in the Content Delivery APIs. Each query parameter within the table has a corresponding description, the API requests it is used in, and a relevant example. Use it as a cheat sheet or quick reference to search API requests by query parameters.

Query Parameter API Requests
include_count
environment
  • All Content Delivery API requests (except Subsequent Sync and Sync using pagination token requests)
locale
version
relative_urls
include_dimension
init
content_type_uid
start_from
type
pagination_token
sync_token
query
include[]
limit
skip
asc

desc
only
exclude
top-arrow