---
title: "Contentstack Delivery Java SDK"
description: "Documentation for Java Delivery SDK"
url: "https://www.contentstack.com/docs/developers/sdks/content-delivery-sdk/java/reference"
product: "Contentstack"
doc_type: "guide"
audience:
  - developers
  - admins
version: "current"
last_updated: "2025-09-15"
---

# Contentstack Delivery Java SDK

## Contentstack - Java Delivery SDK

## Java Delivery SDK for Contentstack

Contentstack is a headless CMS with an API-first approach. It is a CMS that developers can use to build powerful cross-platform applications in their favorite languages. Build your application frontend, and Contentstack will take care of the rest. [Read More](https://www.contentstack.com/docs/developers/java/).

Contentstack provides Java Delivery SDK to build application on top of Java. Given below is the detailed guide and helpful resources to get started with our Java Delivery SDK.

## Prerequisite

To get started with Java SDK, you will need the following:

*   An IDE. You can use an IDE of your choice, but make sure it supports Java.
*   Java SDK version 1.8 or later

## SDK Installation and Setup

Add the following dependency code snippets into your project:

**Maven**

<dependency>
  <groupid>com.contentstack.sdk</groupid>
  <artifactid>java</artifactid>
  <version>{version}</version>
</dependency>

Maven users need to add the above code in your `pom.xml` file under the `<dependencies>` section.

**Gradle**

implementation'com.contentstack.sdk:java:{version}

Gradle users need to add the above dependency code into your `build.gradle` file.

You can download the latest dependency version [here](https://mvnrepository.com/artifact/com.contentstack.sdk/java).

## Quickstart in 5 mins

## Initializing your SDK

To initialize the SDK, you will need to specify the stack’s **APIKey, Delivery Token,** and **Environment** where you will publish your content.

import com.contentstack.sdk.\*;  
  
Stack stack = Contentstack.stack("APIKey","deliveryToken","environmentName");

**Note** : By default, the SDK uses the North American region. Configuration changes are not required for North American region users.

**For setting the Region refer to the code below:**

import com.contentstack.sdk.\*;  
  
Config config = Config();  
Config.region = ContentstackRegion.EU;  
Stack stack = Contentstack.stack("APIKey", "deliveryToken", "environmentName", config);  

**For setting the Branch refer to the code below:**

import com.contentstack.sdk.\*;  
  
Config config = Config();  
config.setBranch("branch");  
Stack stack = Contentstack.stack("APIkey", "deliveryToken", "environmentName", config);

**Note**:For Europe, set the region as **EU**, for Azure North America , set the region as **AZURE\_NA**, for Azure Europe, set the region as **AZURE\_EU**, for GCP North America, set the region as **GCP\_NA**, for GCP Europe, set the region as **GCP\_EU.**

## Basic Queries

Contentstack SDKs let you interact with the [Content Delivery APIs](/docs/developers/apis/content-delivery-api/) 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.

**Get a Single Entry**

To retrieve a single [Entry](/docs/developers/apis/content-delivery-api/) from a [Content Type](/docs/developers/apis/content-delivery-api/#content-types), use the code snippet given below:

import com.contentstack.sdk.\*;  
Stack stack = Contentstack.stack("APIKey", "deliveryToken", "environmentName");  
ContentType contentType = stack.contentType("contentTypeUid");  
Entry entry = contentType.entry("entryUid");  
entry.fetch(new EntryResultCallBack() {  
@Override  
public void onCompletion(ResponseType responseType, Error error) {  
if (error == null) {  
  System.out.println(entry);  
}});

**Get Multiple Entries**

To retrieve multiple entries of a particular content type, use the code snippet given below:

import com.contentstack.sdk.\*;  
Stack stack = Contentstack.stack("APIKey", "deliveryToken", "environmentName");  
Query query = stack.contentType("contentTypeUid").query();  
query.find(new QueryResultsCallBack){  
 @Override  
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error) {  
if (error == null) {  
}}  
});

**Note:**

*   Currently, the Java SDK does not support multiple content types referencing in a single query. For more information on how to query entries and assets, refer the [Queries](/docs/developers/apis/content-delivery-api/#queries)section of our Content Delivery API documentation
*   By default, the limit for response details per request is 100, with the maximum limit set at 250.

## Pagination

In a single instance, the [Get Multiple Entries](https://contentstack-docs.vercel.app/docs/developers/apis/content-delivery-api/#entries) query will **retrieve only the first 100 items** of the specified content type. You can paginate and retrieve the rest of the items in batches using the **skip** and **limit** parameters in subsequent requests.

import com.contentstack.sdk.\*;  
  
Stack stack = Contentstack.stack("APIKey","deliveryToken","environmentName");   
Query query = stack.contentType("contentTypeUid").query();   
query.skip(20).limit(20).find(newQueryResultsCallBack(){   
@Override   
public void onCompletion(ResponseType responseType, QueryResult queryResult, Error error){  
  
}});

## Contentstack

A [stack](/docs/developers/set-up-stack/about-stack) is a repository or a container that holds all the [entries](/docs/content-managers/author-content/about-entries)/[assets](/docs/content-managers/working-with-assets/about-assets) of your site. It allows multiple users to [create](/docs/content-managers/working-with-entries/create-an-entry), [edit](/docs/content-managers/working-with-entries/edit-an-entry), [approve](/docs/content-managers/use-workflows/send-an-entry-for-publish-or-unpublish-approval), and [publish](/docs/content-managers/publish-content) their content within a single space.

The stack function initializes an instance of the Stack. To initialize a stack execute the following code:

## stack

A stack method provides access to the stack of your site. It allows users to get the content within a single space.

API Key of your application on Contentstack

Delivery Tokens retrieves only the published entries of the environment with which it is associated

A publishing environment refers to one or more deployment servers or a content delivery destination (Webpage’s address) where you will publish your content ([entries](https://www.contentstack.com/docs/content-managers/working-with-entries/about-entries/) or [assets](https://www.contentstack.com/docs/content-managers/working-with-assets/about-assets/)).

Config instance to set environment and other configuration details.

## Contentstack

## Config

Config class that exposes config instance, Where the user can provide other configurations on the stack

## earlyAccess

With the earlyAccess header support, you can access features that are part of the early access program.

## getBranch

Get branch of the stack

## setBranch

Set branch for on the stack

branch you want to set

## setProxy

Sets custom proxy

Proxy setting, typically a type (http, socks) and a socket address. A Proxy is an immutable object

## getProxy

Returns the Proxy instance

## connectionPool

Manages reuse of HTTP and HTTP/2 connections for reduced network latency. HTTP requests that \* share the same {@link okhttp3.Address} may share a {@link okhttp3.Connection}. This class implements the policy of which connections to keep open for future use.

the maxIdleConnections default value is 5

the keepAliveDuration default value is 5

the timeUnit default value is TimeUnit.MINUTES

## getRegion

Get Region of the request url

## setRegion()

Sets Region of the database

DB region for your stack. You can choose from six regions namely, NA, EU, Azure NA, Azure EU, GCP NA, and GCP EU.

## getHost()

Gets host of the request

## setHost()

Set custom host of the request url

The host

## getVersion()

Gets version of the request path

## enableLivePreview()

Enables Live Preview

Provide true to enable the Live Preview

## setLivePreviewHost()

Sets Host to the Live Preview request url

Host for Live Preview

## setManagementToken()

Adds Management Token to the stack header

The Management Token

## Config

## Asset

In Contentstack, any files (images, videos, PDFs, audio files, and so on) that you upload get stored in your repository for future use. This repository of uploaded files is called Assets.

These are the keys that can be passed for addParam.

Key

Value

Description

include\_fallback

boolean

Enter true to include published localized content from the fallback locale when the specified locale lacks published content.

include\_dimension

boolean

Set to true to include the image dimensions (height and width) in the response. Supported image formats include JPG, GIF, PNG, WebP, BMP, TIFF, SVG, and PSD.

include\_branch

boolean

Set to true to include the \_branch top-level key in the response. This key indicates the unique ID of the branch where the specified Contentstack module resides.

version

number

Enter the latest version number. Providing a draft version number will result in an empty response.

loorelative\_urlsb

string

Enter the language code for which you want to include entries. Only published, localized entries will be displayed.

## getUpdatedBy

Gets UpdatedBy object from the asset response

## setHeader

Add header using key and value

The key you want to remove from the header

Value of the header against the key

## removeHeader

Removes header using key

Key of the header you want to remove

## sort

Sort assets.

the key order by

the orderby can be applied using ORDERBY enums

## includeCount

Include count of asset.

## includeRelativeUrl

Include relative url asset.

## includeFallback

Includes Fallback language in the asset response.

## includeMetadata

Includes asset metadata along with response body.

## getCount

Returns list of all assets available in the stack.

## getAssetUid

Gets AssetUid object from the asset response

## getFileType

Gets FileType object from the asset response

## getFileSize

Gets FileSize object from the asset response

## getFileName

Gets FileName object from the asset response

## getUrl

Gets getUrl object from the asset response

## toJSON

Gets JSON object from the asset response

## getCreateAt

Gets CreateAt object from the asset response

## getCreatedBy

Gets CreatedBy object from the asset response

## getUpdateAt

Gets UpdateAt object from the asset response

## getDeleteAt

Gets Deleted At object from the asset response

## getDeletedBy

Gets Deleted by object from the asset response

## getTags

Includes Array of tags in the asset response

## setTags

Includes Tags in the asset response

## includeDimension

Inludes Dimension in the asset response

## addParam

Add query parameter to the asset request

These are the keys that can be passed for addParam.

Key

Value

Description

include\_fallback

boolean

Enter true to include published localized content from the fallback locale when the specified locale lacks published content.

include\_dimension

boolean

Set to true to include the image dimensions (height and width) in the response. Supported image formats include JPG, GIF, PNG, WebP, BMP, TIFF, SVG, and PSD.

include\_branch

boolean

Set to true to include the \_branch top-level key in the response. This key indicates the unique ID of the branch where the specified Contentstack module resides.

version

number

Enter the latest version number. Providing a draft version number will result in an empty response.

relative\_urls

boolean

Set 'true' to include the relative URL of the asset in the response

include\_path

boolean

Set to true to add a path array to the response, displaying the hierarchical folder structure of the asset or folder.

Key of the header you want to add

Add value to the header against the header key

## includeBranch

Includes Branch in the asset response

## fetch

Fetch all the assets available in the stack

callback of the asset response

## setLocale

The setLocale method sets the locale (language) for the asset request. Use before fetch() to request localized asset data.

## getLocale

The getLocale method returns the locale (language) of the asset. This value is obtained from the response after the asset is fetched and configured.

## assetFields

The assetFields method acts as a filter for the API response, ensuring you get exactly the asset metadata you need. It specifies the asset-related field groups to include in the API response when you fetch a single entry.

**Note:** The assetFields method is supported only in the North America (NA) region.

One or more asset field groups to include in the response.

## Config

## AssetLibrary

In Contentstack, any files (images, videos, PDFs, audio files, and so on) that you upload get stored in your repository for future use. This repository of uploaded files is called Assets.

## sort

The sort method sorts the asset library based on order criteria.

the key order by

the orderby can be applied using ORDERBY enums

## includeCount

The includeCount method includes the total count of assets in the asset library response.

## includeRelativeUrl

The includeRelativeUrl method includes the relative URLs of assets in the asset library response.

## includeMetadata

Includes asset metadata along with response body.

## where

The where() method retrieves the assets from the stack using any other field UID of the assets.

Field UID of the Asset

Value of the Asset

## addParam

The addParam method adds a query parameter to the query.

Pass the key

Pass the value

## removeParam

The removeParam method removes a query parameter from the query.

Pass the key to be removed as a param

## limit

The limit method will return a specific number of assets in the output.

Enter the number of assets to be returned.

## skip

The skip method will skip a specific number of assets in the output.

Enter the number of assets to be skipped.

## Pagination

In a single instance, a query will retrieve only the first 100 items in the response. You can paginate and retrieve the rest of the items in batches using the skip and limit methods.

## setLocale

The setLocale method sets the locale used for asset queries, so results are returned for a specific language or region.

Locale code for the query (for example, "en-us"). Used in requests built with fetchAll() to determine which localized asset data is returned.

## Config

## ContentType

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.

## removeHeader

Removes header from the stack using headerKey

The key of the header

## entry

An Entry is the actual piece of content created using one of the defined content types.

The entry unique ID of the entry that you want to fetch

## query

Provides query instance

## fetch

fetch all the content types available for the stack

key value parameters of type JSONObject

The callback of type ContentTypesCallback

## Entry

An entry is the actual piece of content created using one of the defined content types.

## removeHeader

Removes header using key

key of the header you want to remove

## getTags

Gets entry tags

## getContentType

Gets entry content type

## getUid

Gets entry uid

## getLocale

Gets Language of the entry

## setLocale

Sets locale of entry

language code

## except

Specifies list of field uids that would be excluded from the response

field uid which get excluded from the response.

## includeReference

Add a constraint that requires a particular reference key details.

referenceFields array key that to be constrained

## only

Specifies an array of only keys in BASE object that would be included in the response

Array of the only reference keys to be included in response

## onlyWithReferenceUid

Specifies an array of only keys that would be included in the response.

Array of the only reference keys to be included in response.

Key who has reference to some other class object

## exceptWithReferenceUid()

Specifies an array of except keys that would be exclude in the response

Array of the except reference keys to be excluded in response

Key who has reference to some other class object

## fetch

fetch is used to get the entry response

EntryResultCallBack object to notify the application when the request has completed

## addParam

Adds query parameters in the entry request

These are the keys that can be passed for addParam.

Key

Value

Description

include\_fallback

boolean

Enter true to include published localized content from the fallback locale when the specified locale lacks published content.

locale

string

Enter the language code for which you want to include entries. Only published, localized entries will be displayed.

include\_branch

boolean

Set to true to include the \_branch top-level key in the response. This key indicates the unique ID of the branch where the specified Contentstack module resides.

version

number

Enter the latest version number. Providing a draft version number will result in an empty response.

key of the header

value of the header

## includeReferenceContentTypeUID

Include Reference ContentType UID in the entry response

## includeContentType

Include ContentType in the entry response

## includeFallback

Include Fallback Language in the entry response

## includeEmbeddedItems

Include Embedded Items in the entry response

## includeBranch

include branch in the entry response

## includeMetadata

Includes entry metadata along with response body.

## variants

The variants method retrieves details of a specific entry variant or an array of entry variants based on the applied query.

When Personalize creates a variant in the CMS, it assigns a "Variant Alias" to identify that specific variant. When fetching entry variants using the Delivery API, you can pass variant aliases in place of variant UIDs in the x-cs-variant-uidheader.

Enter the UID/Alias of the variant

## assetFields

The assetFields method acts as a filter for the API response, ensuring you get exactly the asset metadata you need. It specifies the asset-related field groups to include in the API response when you fetch a single entry.

**Note:** The assetFields method is supported only in the North America (NA) region.

One or more asset field groups to include in the response.

## Config

## Taxonomy

Taxonomy helps you categorize pieces of content within your stack to facilitate easy navigation and retrieval of information.

To access the taxonomy instance, use the code snippet provided below within the stack class:

Stack stack = Contentstack.stack("API\_KEY", "DELIVERY\_TOKEN", "ENVIRONMENT");  
Taxonomy taxonomy = stack.taxonomy();

## in

The in method retrieves all entries for a specific taxonomy that satisfy the given conditions provided in the $in query.

Enter the UID of the taxonomy

Enter the list of taxonomy fields

## or

The or method retrieves all entries for a specific taxonomy that satisfy at least one of the given conditions provided in the $or query.

Enter the list of taxonomy fields

## and

The and method retrieves all entries for a specific taxonomy that satisfy all the conditions provided in the $and query.

Enter the list of taxonomy fields

## exists

The exists method retrieves all entries for a specific taxonomy if the value of the field, mentioned in the condition, exists.

Enter the UID of the taxonomy

Enter true/false

## equalAndBelow

The equalAndBelow method retrieves all entries for a specific taxonomy that match a specific term and all its descendant terms, requiring only the target term.

Enter the UID of the taxonomy

Enter the UID of the term

## equalAndBelowWithLevel

The equalAndBelowWithLevel method retrieves all entries for a specific taxonomy that match a specific term and all its descendant terms, requiring only the target term and a specified level.

**Note**: If you don't specify the level, the default behavior is to retrieve terms up to level 10.

Enter the UID of the taxonomy

Enter the UID of the term

Enter the level

## below

The below method retrieves all entries for a specific taxonomy that match all of their descendant terms by specifying only the target term and a specific level.

**Note**: If you don't specify the level, the default behavior is to retrieve terms up to level 10.

Enter the UID of the taxonomy

Enter the UID of the term

## equalAbove

The equalAbove method retrieves all entries for a specific taxonomy that match a specific term and all its ancestor terms, requiring only the target term and a specified level.

**Note**: If you don't specify the level, the default behavior is to retrieve terms up to level 10.

Enter the UID of the taxonomy

Enter the UID of the term

## above

The above method retrieves all entries for a specific taxonomy that match only the parent term(s) of a specified target term, excluding the target term itself and a specified level.

**Note**: If you don't specify the level, the default behavior is to retrieve terms up to level 10.

Enter the UID of the taxonomy

Enter the UID of the term

## find

The find method is used to get the API response.

The callback class that contains the API response

## Query

The Get all entries request fetches the list of all the entries of a particular content type. It returns the content of each entry in JSON format. You need to specify the environment and locale of which you want to get the entries. We can apply filters on query also.

## removeHeader

Remove header key

key of the header you want to remove

## getContentType

Gets the content type

## where

Add a constraint to fetch all entries that contains given value against specified key

key of query parameter

value of query param

## addQuery

Add a custom query against specified key.

key of query parameter

value of query param

## removeQuery

Remove provided query key from custom query if exist.

Query name to remove.

## and

Combines all the queries together using AND operator

List of Query instances on which AND query executes.

## or

Add a constraint to fetch all entries which satisfy any queries.

the value that provides an upper bound

## lessThan

Add a constraint to the query that requires a particular key entry to be less than the provided value.

The key to be constrained

the value that provides an upper bound

## lessThanOrEqualTo

Add a constraint to the query that requires a particular key entry to be less than or equal to the provided value

The key to be constrained

The value that must be equalled.

## greaterThan

Add a constraint to the query that requires a particular key entry to be greater than the provided value.

The key to be constrained

The value that provides an lower bound.

## greaterThanOrEqualTo

Add a constraint to the query that requires a particular key entry to be greater than or equal to the provided value.

The key to be constrained

The list of values the key object should not be.

## notEqualTo

Add a constraint to the query that requires a particular key's entry to be contained in the provided array

The key to be constrained

The list of values the key object should not be.

## notContainedIn

Add a constraint to the query that requires a particular key's entry to be contained in the provided array

The key to be constrained

The list of values the key object should not be.

## notContainedIn

Add a constraint to the query that requires a particular key entry's value not be contained in the provided array.

The key to be constrained

The list of values the key object should not be.

## exists

Add a constraint that requires, a specified key exists in response

The key to be constrained

## notExists

Add a constraint that requires, a specified key does not exists in response.

The key to be constrained

## includeReference

Add a constraint that requires a particular reference key details

key that to be constraineda

## tags

Include tags with which to search entries

Comma separated array of tags with which to search entries.

## ascending

Sort the results in ascending order with the given key. <br> Sort the returned entries in ascending order of the provided key.

The key to order by.

## descending

Sort the results in descending order with the given key. <br> Sort the returned entries in descending order of the provided key.

The key to order by.

## only

Specifies an array of only keys in BASE object that would be included in the response.

## exceptWithReferenceUid

Specifies an array of only keys that would be included in the response

Array of the only reference keys to be included in response

Key who has reference to some other class object

## exceptWithReferenceUid

Specifies an array of except keys that would be excluded in the response.

## count

Retrieve count and data of objects in result

## includeCount

Retrieve count and data of objects in result

## includeContentType

Include Content Type of all returned objects along with objects themselves

## includeOwner

Include object owner's profile in the objects data.

## skip

The number of objects to skip before returning any.

Number of objects to skip from returned objects

## limit

A limit on the number of objects to return.

Number of objects to limit.

## regex

Add a regular expression constraint for finding string values that match the provided regular expression. This may be slow for large data sets.

The key to be constrained.

The regular expression pattern to match

Any of the following supported Regular expression modifiers.

\- use i for case-insensitive matching.

\- use m for making dot match newlines.

\- use x for ignoring whitespace in regex

## locale

Set Language using locale code.

language code

## search

This method provides only the entries matching the specified value.

value used to match or compare

## find

Execute a Query and Caches its result (Optional)

QueryResultsCallBack object to notify the application when the request has completed.

## findOne

This Execute a Query and Caches its result (Optional)

The key as string which needs to be added to the Query

## addParam

This method adds key and value to an Entry. Parameters

The key as string which needs to be added to the Query

The value as string which needs to be added to the Query

## includeReferenceContentTypUid

This method also includes the content type UIDs of the referenced entries returned in the response

## whereNotIn

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

The key to be constrained

queryObject is Query object, so you can chain this call

## whereNotIn

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.

The key to be constrained

Query object, so you can chain this call

## includeFallback

Includes language fallback in the query response

## includeEmbeddedItems

Includes Embedded Items in the query response

## includeBranch

Includes Branch in the entry response

## Global Fields

A [Global field](/docs/developers/global-field/about-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.

## fetch

The fetch method retrieves the global field data of the specified global field.

## findAll

The findAll method retrieves all the global fields of the stack.

## includeBranch

The includeBranch method includes the branch details in the result for single or multiple global fields.

## includeGlobalFieldSchema

The includeGlobalFieldSchema method includes the schema of the global field in the response.