Entry
Entry
An entry is one piece of content created from a content type. Use this class to
- create, read, update, and delete the entries of one content type
- localize an entry, name its versions, and read its references and locales
- publish and unpublish an entry, and move it through a workflow
- create, read, publish, and delete the variants of an entry
stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>") returns an Entry for one entry. The two calls take one argument each:
| Name | Type | Description |
|---|---|---|
| contentTypeUid | String | UID of the content type. Pass it to stack.contentType(). |
| entryUid | String | UID of the entry. Pass it to entry(). Leave it out to work with all entries of the content type. |
Entry has no public constructor. The entry method of ContentType creates it.
addBranch
addBranch sets the branch header on this entry object, so that every later request from it reads or changes that branch.
| Name | Type | Description |
|---|---|---|
| branchUid (required) | String | UID or alias of the branch to target. |
Returns: Entry. The same entry, for chaining.
Validation
- Throws NullPointerException if branchUid is null, and IllegalArgumentException if it is empty or only whitespace, because the request needs a branch value to send.
- There is no other client-side validation.
- An unknown branch surfaces as an API error in the response when you call execute() on the request this method feeds.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Replaces the branch header that the entry copied from the stack. The change applies to this entry object only. The stack, the content type, and other entries keep their branch.
- Every later request from this entry sends the new header, including the variant, publish, and unpublish requests.
- addHeader("branch", "<BRANCH>") sets the same header without the checks.
- The branchUid argument of fetchEntryVariant replaces this header for one request.
Example
Basic usage: read an entry on a branch
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class FetchEntryOnBranch {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry("<ENTRY_UID>")
.addBranch("<BRANCH>");
Response<ResponseBody> response = entry.fetch().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}Edge case: a stack branch and an entry branch together
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.ContentType;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class OverrideStackBranch {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
ContentType contentType = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>", "main")
.contentType("<CONTENT_TYPE_UID>");
// This entry reads <BRANCH>. Other entries from contentType still read main.
Response<ResponseBody> response = contentType.entry("<ENTRY_UID>")
.addBranch("<BRANCH>")
.fetch()
.execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}addHeader
addHeader adds one header to every later request from this entry.
| Name | Type | Description |
|---|---|---|
| key (required) | String | Name of the header, such as api_version. |
| value (required) | String | Value of the header. |
Returns: Entry. The same entry, for chaining.
Validation
- There is no client-side validation.
- A null key or value makes execute() throw IllegalArgumentException on every later request from this entry, because Retrofit rejects a header map that holds null.
- An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Puts the header into the header map of this entry. The new value replaces a header with the same name, including the api_key, authorization, and branch headers that the entry copied from the stack.
- Every request method of this entry sends the header map. The header stays until you create a new entry object.
- The header map belongs to this entry object. The stack, the content type, and other entries do not see the header.
- addHeader("branch", "<BRANCH>") works like addBranch. addHeader("api_version", "3.2") replaces the value that publishEntryVariants and unpublishEntryVariants add.
Example
Basic usage: send the api_version header with a publish request
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import org.json.simple.JSONArray;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class PublishWithApiVersion {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry("<ENTRY_UID>")
.addHeader("api_version", "3.2");
JSONArray environments = new JSONArray();
environments.add("<ENVIRONMENT>");
JSONObject details = new JSONObject();
details.put("environments", environments);
JSONObject body = new JSONObject();
body.put("entry", details);
Response<ResponseBody> response = entry.publish(body).execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}addHeaders
addHeaders adds several headers to every later request from this entry.
| Name | Type | Description |
|---|---|---|
| headers (required) | HashMap<String, String> | Header names mapped to their values. |
Returns: Entry. The same entry, for chaining.
Validation
- Throws NullPointerException if headers is null, because the SDK copies every pair from the map.
- A null key or value in the map makes execute() throw IllegalArgumentException on later requests. Retrofit rejects a header map that holds null.
- An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Copies every pair into the header map of this entry. Each new value replaces a header with the same name.
- Every request method of this entry sends the header map. The headers stay until you create a new entry object.
- The SDK copies the pairs, so later changes to your map do not reach the entry.
- addHeader adds one header.
Example
Basic usage: add a branch and an api_version header
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
import java.util.HashMap;
public class AddEntryHeaders {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
HashMap<String, String> headers = new HashMap<>();
headers.put("branch", "<BRANCH>");
headers.put("api_version", "3.2");
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry("<ENTRY_UID>")
.addHeaders(headers);
Response<ResponseBody> response = entry.fetch().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}addParam
addParam adds one query parameter to the later requests from this entry, such as locale or include_publish_details.
| Name | Type | Description |
|---|---|---|
| key (required) | String | Name of the query parameter, such as locale. |
| value (required) | Object | Value of the parameter. The SDK sends its toString() form. |
Returns: Entry. The same entry, for chaining.
Validation
- There is no client-side validation.
- A null key or value makes execute() throw IllegalArgumentException on every later request that sends the parameter map, because Retrofit rejects a query map that holds null.
- An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Puts the parameter into the query parameter map of this entry. The new value replaces a parameter with the same name.
- The parameter stays on the entry. Every later request that sends the map carries it, until you call removeParam.
- Every request method sends the map except atomicOperation, localize, unLocalize, versionName, deleteVersionName, and query.
- Which parameters the API accepts depends on the request. For example, Get a single entry accepts version, locale, include_workflow, include_publish_details, and include_branch. Each method page names the parameters of its request.
- The map belongs to this entry object. Entries that you create later from the same content type start with an empty map.
Example
Basic usage: read an entry in one locale with its publish details
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class FetchLocalizedEntry {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry("<ENTRY_UID>")
.addParam("locale", "<LOCALE>")
.addParam("include_publish_details", true);
Response<ResponseBody> response = entry.fetch().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}Edge case: read an earlier version of the entry
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class FetchEntryVersion {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry("<ENTRY_UID>")
.addParam("version", 2);
Response<ResponseBody> response = entry.fetch().execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
// The version parameter stays on the entry. Remove it before the next request.
entry.removeParam("version");
}
}addParams
addParams adds several query parameters to the later requests from this entry.
| Name | Type | Description |
|---|---|---|
| params (required) | HashMap<String, Object> | Parameter names mapped to their values. |
Returns: Entry. The same entry, for chaining.
Validation
- Throws NullPointerException if params is null, because the SDK copies every pair from the map.
- A null key or value in the map makes execute() throw IllegalArgumentException on later requests that send the map. Retrofit rejects a query map that holds null.
- An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Copies every pair into the query parameter map of this entry. Each new value replaces a parameter with the same name.
- The requests that send the map are the same as for addParam.
- The SDK copies the pairs, so later changes to your map do not reach the entry.
Example
Basic usage: list entries of one locale with workflow details
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
import java.util.HashMap;
public class FindEntriesWithParams {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
HashMap<String, Object> params = new HashMap<>();
params.put("locale", "<LOCALE>");
params.put("include_workflow", true);
params.put("include_publish_details", true);
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry()
.addParams(params);
Response<ResponseBody> response = entry.find().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}atomicOperation
atomicOperation changes field values of an entry with the atomic operators PUSH, PULL, UPDATE, ADD, and SUB, so that concurrent edits do not overwrite each other.
| Name | Type | Description |
|---|---|---|
| requestBody (required) | JSONObject | Request body with the operations under an entry key. |
| requestBody.entry (required) | JSONObject | Field UIDs mapped to one operator object each. |
Returns: Call<ResponseBody>. The request for the entry after the atomic update, sent when you call execute().
Validation
- Throws NullPointerException if the entry UID is null, as after entry(null), because the request path needs the entry UID.
- A null body makes execute() throw IllegalArgumentException, because Retrofit cannot build a request without a body.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One call builds one PUT /content_types/{content_type_uid}/entries/{entry_uid} request with requestBody as the JSON body, the same path as update.
- atomicOperation sends no query parameters. Values from addParam do not reach this request.
- The API supports the following five operators, one per field:
- PUSH appends data to a field marked Multiple, for example {"entry": {"multiple_number": {"PUSH": {"data": [2, 3]}}}}.
- PULL removes the values that match a query, for example {"entry": {"multiple_number": {"PULL": {"query": {"$in": [2, 3]}}}}}.
- UPDATE replaces the value at one index, for example {"entry": {"multiple_number": {"UPDATE": {"index": 0, "data": 1}}}}.
- ADD increments a Number field by the value you pass, for example {"entry": {"view_count": {"ADD": 1}}}.
- SUB decrements a Number field by the value you pass.
- ADD and SUB read the latest value of the field on the server, so they change it whatever its current value is.
Example
Basic usage: append two values to a multiple Number field
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import org.json.simple.JSONArray;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class PushToEntryField {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry("<ENTRY_UID>");
JSONArray data = new JSONArray();
data.add(2);
data.add(3);
JSONObject push = new JSONObject();
push.put("data", data);
JSONObject operator = new JSONObject();
operator.put("PUSH", push);
JSONObject fields = new JSONObject();
fields.put("multiple_number", operator);
JSONObject body = new JSONObject();
body.put("entry", fields);
Response<ResponseBody> response = entry.atomicOperation(body).execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}Counter: increment one Number field and decrement another
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class IncrementEntryCounter {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry("<ENTRY_UID>");
JSONObject add = new JSONObject();
add.put("ADD", 1);
JSONObject sub = new JSONObject();
sub.put("SUB", 1);
JSONObject fields = new JSONObject();
fields.put("view_count", add);
fields.put("stock_count", sub);
JSONObject body = new JSONObject();
body.put("entry", fields);
Response<ResponseBody> response = entry.atomicOperation(body).execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}create
create creates an entry in the content type from the field values you send.
| Name | Type | Description |
|---|---|---|
| requestBody (required) | JSONObject | Request body with the entry under an entry key. |
| requestBody.entry (required) | JSONObject | Field UIDs mapped to their values, such as title and url. |
Returns: Call<ResponseBody>. The request for the new entry, sent when you call execute().
Validation
- There is no client-side validation of the body.
- A null body makes execute() throw IllegalArgumentException, because Retrofit cannot build a request without a body.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One call builds one Create an entry request (POST /content_types/{content_type_uid}/entries) with requestBody as the JSON body.
- The request sends the query parameters of this entry. locale sets the language of the new entry, and include_branch adds the _branch key to the response.
- The field values must match the schema of the content type. A reference field takes an array of objects with uid and _content_type_uid, as Create an entry shows.
- create ignores the entry UID, so call it on entry().
- The API does not publish the new entry. Publish it with publish.
Example
Basic usage: create an entry with a title and URL
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class CreateEntry {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry();
JSONObject fields = new JSONObject();
fields.put("title", "docs-test-blog-post");
fields.put("url", "/docs-test-blog-post");
JSONObject body = new JSONObject();
body.put("entry", fields);
Response<ResponseBody> response = entry.create(body).execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}Reference field and locale: create a localized entry that references an author
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import org.json.simple.JSONArray;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class CreateEntryWithReference {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry()
.addParam("locale", "<LOCALE>");
JSONObject author = new JSONObject();
author.put("uid", "<ENTRY_UID>");
author.put("_content_type_uid", "author");
JSONArray authors = new JSONArray();
authors.add(author);
JSONObject fields = new JSONObject();
fields.put("title", "docs-test-blog-post-with-author");
fields.put("url", "/docs-test-blog-post-with-author");
fields.put("author", authors);
JSONObject body = new JSONObject();
body.put("entry", fields);
Response<ResponseBody> response = entry.create(body).execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}createEntryVariant
createEntryVariant creates a variant of an entry from the fields that differ from the base entry.
| Name | Type | Description |
|---|---|---|
| variantUid (required) | String | UID of the variant. |
| requestBody (required) | JSONObject | Request body with the variant fields under an entry key. |
| requestBody.entry (required) | JSONObject | Field UIDs mapped to the values that differ from the base entry. |
Returns: Call<ResponseBody>. The request for the new entry variant, sent when you call execute().
Validation
- Throws NullPointerException if the entry UID is null, as after entry(null), because the request path needs the entry UID.
- Throws NullPointerException if variantUid is null, and IllegalArgumentException if it is empty or only whitespace, because the request path needs the variant UID.
- A null body makes execute() throw IllegalArgumentException, because Retrofit cannot build a request without a body.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One call builds one Create entry variant request (PUT /content_types/{content_type_uid}/entries/{entry_uid}/variants/{variant_uid}) with requestBody as the JSON body.
- updateEntryVariant sends the same request. The API creates the variant when it does not exist and updates it when it does.
- The request sends the query parameters of this entry. The API accepts locale for the language of the variant.
- The request sends the branch header of this entry: the stack branch, or the one from addBranch.
- Link the content type to a variant group before you call this method, as Create entry variant states. Fields you leave out keep the values of the base entry.
- For Group and Modular Blocks fields with several instances, the API reads the _order property to set the order of the instances.
Example
Basic usage: create a variant with a new title and URL
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class CreateEntryVariant {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry("<ENTRY_UID>")
.addParam("locale", "<LOCALE>");
JSONObject fields = new JSONObject();
fields.put("title", "docs-test-blue-variant");
fields.put("url", "/docs-test-blue-variant");
JSONObject body = new JSONObject();
body.put("entry", fields);
Response<ResponseBody> response = entry.createEntryVariant("<VARIANT_UID>", body).execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}delete
delete deletes an entry, one of its localized versions, or several localized versions at once.
| Name | Type | Description |
|---|---|---|
| requestBody (required) | JSONObject | Request body that names the localized versions to delete. |
| requestBody.entry.locales (required) | JSONArray | Locale codes of the localized versions to delete. |
Returns: Call<ResponseBody>. The request for the entry deletion, sent when you call execute().
Overloads
- delete(): This overload takes no parameters.
- delete(JSONObject requestBody)
Validation
- Throws NullPointerException if the entry UID is null, as after entry(null), because the request path needs the entry UID.
- A null body makes execute() throw IllegalArgumentException, because Retrofit cannot build a request without a body.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One call builds one Delete an entry request (DELETE /content_types/{content_type_uid}/entries/{entry_uid}). delete() sends an empty JSON object as the body.
- The request sends the query parameters of this entry. They choose what the API deletes in one of the following three ways:
- With no locale and no delete_all_localized, the API deletes the master language entry.
- locale deletes the localized version in that locale.
- delete_all_localized set to true deletes the master language entry and all of its localized versions.
- delete(JSONObject) deletes the localized versions that requestBody.entry.locales lists.
Example
Basic usage: delete the master language entry
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class DeleteEntry {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry("<ENTRY_UID>");
Response<ResponseBody> response = entry.delete().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}Query parameters: delete the entry in every locale
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class DeleteEntryAllLocales {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry("<ENTRY_UID>")
.addParam("delete_all_localized", true);
Response<ResponseBody> response = entry.delete().execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}Request body: delete two localized versions
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import org.json.simple.JSONArray;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class DeleteLocalizedVersions {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry("<ENTRY_UID>");
JSONArray locales = new JSONArray();
locales.add("fr-fr");
locales.add("de-de");
JSONObject details = new JSONObject();
details.put("locales", locales);
JSONObject body = new JSONObject();
body.put("entry", details);
Response<ResponseBody> response = entry.delete(body).execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}deleteEntryVariant
deleteEntryVariant deletes one variant of an entry. The base entry stays.
| Name | Type | Description |
|---|---|---|
| variantUid (required) | String | UID of the variant to delete. |
Returns: Call<ResponseBody>. The request for the entry variant deletion, sent when you call execute().
Validation
- Throws NullPointerException if the entry UID is null, as after entry(null), because the request path needs the entry UID.
- Throws NullPointerException if variantUid is null, and IllegalArgumentException if it is empty or only whitespace, because the request path needs the variant UID.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One call builds one Delete entry variant request (DELETE /content_types/{content_type_uid}/entries/{entry_uid}/variants/{variant_uid}).
- The request sends the query parameters of this entry. The API accepts locale.
- The request sends the branch header of this entry: the stack branch, or the one from addBranch.
Example
Basic usage: delete a variant of an entry
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class DeleteEntryVariant {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry("<ENTRY_UID>");
Response<ResponseBody> response = entry.deleteEntryVariant("<VARIANT_UID>").execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}deleteVersionName
deleteVersionName removes the name of one version of an entry, so that the version shows its number again.
| Name | Type | Description |
|---|---|---|
| versionNumber (required) | int | Version number whose name to remove. |
| requestBody (required) | JSONObject | Request body with the locale under an entry key. |
| requestBody.entry.locale | String | Locale of the entry version. |
Returns: Call<ResponseBody>. The request for the version name removal, sent when you call execute().
Validation
- Throws NullPointerException if the entry UID is null, as after entry(null), because the request path needs the entry UID.
- A null body makes execute() throw IllegalArgumentException, because Retrofit cannot build a request without a body.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One call builds one Delete Version Name of Entry request (DELETE /content_types/{content_type_uid}/entries/{entry_uid}/versions/{version_number}/name) with requestBody as the JSON body.
- The API resets the name to the version number. The version and its content stay.
- On success the API returns 204 with no content, so response.body() is null. Check response.code() instead of reading the body.
- deleteVersionName sends no query parameters. Values from addParam do not reach this request.
Example
Basic usage: remove the name of version 3
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class DeleteEntryVersionName {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry("<ENTRY_UID>");
JSONObject details = new JSONObject();
details.put("locale", "<LOCALE>");
JSONObject body = new JSONObject();
body.put("entry", details);
Response<ResponseBody> response = entry.deleteVersionName(3, body).execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
// 204 No Content: the body is null
System.out.println("Version name removed: HTTP " + response.code());
}
}detailOfAllVersion
detailOfAllVersion lists the versions of an entry, with the name of each named version.
Returns: Call<ResponseBody>. The request for the entry's version details, sent when you call execute().
Validation
- Throws NullPointerException if the entry UID is null, as after entry(null), because the request path needs the entry UID.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One call builds one Get Details of All Versions of an Entry request (GET /content_types/{content_type_uid}/entries/{entry_uid}/versions).
- The request sends the query parameters of this entry. The API accepts the following five:
- named set to true returns only the named versions.
- include_count adds the total number of versions.
- locale selects the locale. Without it, the API uses the master locale.
- include_updated_at and include_updated_by add the update time and the updating user of each version.
- The API includes _version_name only for a version that has a name. Name a version with versionName.
- For an unlocalized entry, the API returns the versions of the entry in the master locale.
Example
Basic usage: list the versions of an entry
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class ListEntryVersions {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry("<ENTRY_UID>");
Response<ResponseBody> response = entry.detailOfAllVersion().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}Query parameters: list only the named versions in one locale, with a count
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class ListNamedEntryVersions {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry("<ENTRY_UID>")
.addParam("named", true)
.addParam("include_count", true)
.addParam("locale", "<LOCALE>")
.addParam("include_updated_by", true);
Response<ResponseBody> response = entry.detailOfAllVersion().execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}export
export exports an entry as JSON, so that you can keep a copy or import it elsewhere.
Returns: Call<ResponseBody>. The request for the exported entry, sent when you call execute().
Validation
- Throws NullPointerException if the entry UID is null, as after entry(null), because the request path needs the entry UID.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One call builds one Export an entry request (GET /content_types/{content_type_uid}/entries/{entry_uid}/export).
- The request sends the query parameters of this entry. The API accepts locale and include_branch.
- The response body holds the exported entry data. The SDK does not save it to a file. Write response.body().string() to a file yourself.
Example
Basic usage: export an entry to a file
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.FileWriter;
import java.io.IOException;
public class ExportEntry {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry("<ENTRY_UID>")
.addParam("locale", "<LOCALE>");
Response<ResponseBody> response = entry.export().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
try (FileWriter writer = new FileWriter("<FILE_PATH>")) {
writer.write(response.body().string());
}
}
}fetch
fetch reads one entry of the content type.
Returns: Call<ResponseBody>. The request for the entry, sent when you call execute().
Validation
- Throws NullPointerException if the entry UID is null, as after entry(null), because the request path needs the entry UID.
- An entry from entry() holds an empty UID. fetch does not throw for it and sends the request with an empty UID in the path.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One call builds one Get a single entry request (GET /content_types/{content_type_uid}/entries/{entry_uid}).
- The request sends the query parameters of this entry. The API accepts the following five:
- version reads an earlier version of the entry.
- locale reads the entry in one locale.
- include_workflow and include_publish_details add workflow and publish details.
- include_branch adds the _branch key.
- The response body is the raw JSON of the API, with the entry under an entry key. To read the entry as a Java object, use fetchAsPojo.
- The request carries the x-cs-variant-uid header when you called withAppliedVariantUid on this entry.
Example
Basic usage: read one entry
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class FetchEntry {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry("<ENTRY_UID>");
Response<ResponseBody> response = entry.fetch().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}Query parameters: read version 2 of the entry in one locale
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class FetchEntryVersionInLocale {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry("<ENTRY_UID>")
.addParam("version", 2)
.addParam("locale", "<LOCALE>")
.addParam("include_workflow", true);
Response<ResponseBody> response = entry.fetch().execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}Error handling: tell a missing entry from other errors
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.models.Error;
import com.contentstack.cms.stack.Entry;
import com.google.gson.Gson;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class FetchEntryErrorCode {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry("<ENTRY_UID>");
try {
Response<ResponseBody> response = entry.fetch().execute();
if (!response.isSuccessful()) {
// Read the error body once and map it to the SDK's Error model
Error error = new Gson().fromJson(response.errorBody().string(), Error.class);
System.out.println("HTTP " + response.code() + ", error code " + error.getErrorCode()
+ ": " + error.getErrorMessage());
return;
}
System.out.println(response.body().string());
} catch (IOException e) {
// Thrown only when the request does not complete, such as a timeout
System.out.println("Request did not complete: " + e.getMessage());
}
}
}fetchAsPojo
fetchAsPojo reads one entry of the content type and maps it to an EntryPojo object.
Returns: Call<EntryResponse>. The request for the entry as a typed object, sent when you call execute().
Validation
- Throws NullPointerException if the entry UID is null, as after entry(null), because the request path needs the entry UID.
- An API rejection does not throw. response.isSuccessful() is false, response.body() is null, and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends the same Get a single entry request as fetch, with the query parameters and headers of this entry.
- The SDK maps the entry object of the response to an EntryResponse. Other top-level keys of the response do not reach your code.
- EntryResponse has two getters:
- getEntryPojo() returns an EntryPojo with the public fields title, uid, version, and locale, and the other fields in getFields().
- getRawJson() returns the entry as a Gson JsonObject.
- getFields() leaves out the system fields tags, ACL, created_by, updated_by, created_at, updated_at, and _in_progress. Read them from getRawJson().
Example
Basic usage: read the title and a custom field
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import com.contentstack.cms.stack.EntryPojo;
import com.contentstack.cms.stack.EntryResponse;
import retrofit2.Response;
import java.io.IOException;
public class FetchEntryAsPojo {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry("<ENTRY_UID>");
Response<EntryResponse> response = entry.fetchAsPojo().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
EntryPojo pojo = response.body().getEntryPojo();
System.out.println(pojo.title + " (" + pojo.locale + ", v" + pojo.version + ")");
System.out.println("author: " + pojo.getStringField("author"));
System.out.println("created_at: " + response.body().getRawJson().get("created_at"));
}
}fetchEntryVariant
fetchEntryVariant reads one variant of an entry, optionally from a branch that you name for this request only.
| Name | Type | Description |
|---|---|---|
| variantUid (required) | String | UID of the variant to read. |
| branchUid (required) | String | Branch for this request only. null or blank keeps the entry's branch. |
Returns: Call<ResponseBody>. The request for the entry variant, sent when you call execute().
Validation
- Throws NullPointerException if the entry UID is null, as after entry(null), because the request path needs the entry UID.
- Throws NullPointerException if variantUid is null, and IllegalArgumentException if it is empty or only whitespace, because the request path needs the variant UID.
- A null, empty, or blank branchUid does not throw. The request then uses the branch header of the entry.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One call builds one Get single entry variant request (GET /content_types/{content_type_uid}/entries/{entry_uid}/variants/{variant_uid}).
- The request sends the query parameters of this entry. The API accepts locale, include_workflow, include_publish_details, and include_rules.
- Which branch header the request sends depends on the overload:
- fetchEntryVariant(variantUid) sends the branch of the entry: the stack branch, or the one from addBranch.
- fetchEntryVariant(variantUid, branchUid) sends branchUid for this request only. The entry keeps its own branch for later requests.
Example
Basic usage: read one variant
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class FetchEntryVariant {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry("<ENTRY_UID>");
Response<ResponseBody> response = entry.fetchEntryVariant("<VARIANT_UID>").execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}All parameters: read a variant from another branch for one request
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class FetchEntryVariantOnBranch {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>", "main")
.contentType("<CONTENT_TYPE_UID>")
.entry("<ENTRY_UID>")
.addParam("include_publish_details", true);
// This request reads <BRANCH>. Later requests from entry still read main.
Response<ResponseBody> response = entry.fetchEntryVariant("<VARIANT_UID>", "<BRANCH>").execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}fetchEntryVariants
fetchEntryVariants lists the variants of an entry.
Returns: Call<ResponseBody>. The request for all variants of the entry, sent when you call execute().
Validation
- Throws NullPointerException if the entry UID is null, as after entry(null), because the request path needs the entry UID.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One call builds one Get all entry variants request (GET /content_types/{content_type_uid}/entries/{entry_uid}/variants).
- The request sends the query parameters of this entry. The API accepts the following five kinds:
- locale selects the locale.
- include_workflow and include_publish_details add workflow and publish details.
- include_rules adds the publish rules.
- skip and limit page through the variants.
- The request sends the branch header of this entry: the stack branch, or the one from addBranch.
Example
Basic usage: list the variants of an entry
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class ListEntryVariants {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry("<ENTRY_UID>");
Response<ResponseBody> response = entry.fetchEntryVariants().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}Query parameters: read the second page of variants in one locale
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class ListEntryVariantsPaged {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry("<ENTRY_UID>")
.addParam("locale", "<LOCALE>")
.addParam("include_publish_details", true)
.addParam("skip", 10)
.addParam("limit", 10);
Response<ResponseBody> response = entry.fetchEntryVariants().execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}find
find lists the entries of the content type.
Returns: Call<ResponseBody>. The request for all entries of the content type, sent when you call execute().
Validation
- There is no client-side validation.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One call builds one Get all entries request (GET /content_types/{content_type_uid}/entries).
- The request sends the query parameters of this entry. The API accepts locale, include_workflow, include_publish_details, include_branch, and apply_draft. Without locale, the API returns the entries of the master locale.
- The response body is the raw JSON of the API, with the entries under an entries key. To read the entries as Java objects, use findAsPojo.
- find ignores the entry UID, so it lists the same entries on entry() and on entry("<ENTRY_UID>").
- The SDK sends one request and does not ask for further pages.
Example
Basic usage: list the entries of a content type
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class FindEntries {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry();
Response<ResponseBody> response = entry.find().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}Query parameters: list the entries of one locale with workflow and publish details
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class FindLocalizedEntries {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry()
.addParam("locale", "<LOCALE>")
.addParam("include_workflow", true)
.addParam("include_publish_details", true);
Response<ResponseBody> response = entry.find().execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}Error handling: read the error code
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.models.Error;
import com.contentstack.cms.stack.Entry;
import com.google.gson.Gson;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class FindEntriesErrorCode {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry();
try {
Response<ResponseBody> response = entry.find().execute();
if (!response.isSuccessful()) {
// Read the error body once and map it to the SDK's Error model
Error error = new Gson().fromJson(response.errorBody().string(), Error.class);
System.out.println("API error " + error.getErrorCode() + ": " + error.getErrorMessage());
return;
}
System.out.println(response.body().string());
} catch (IOException e) {
// Thrown only when the request does not complete, such as a timeout
System.out.println("Request did not complete: " + e.getMessage());
}
}
}findAsPojo
findAsPojo lists the entries of the content type and maps them to EntryPojo objects.
Returns: Call<EntryListResponse>. The request for all entries of the content type as typed objects, sent when you call execute().
Validation
- There is no client-side validation.
- An API rejection does not throw. response.isSuccessful() is false, response.body() is null, and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends the same Get all entries request as find, with the query parameters of this entry.
- The SDK maps the entries array of the response to an EntryListResponse. Other top-level keys of the response do not reach your code. Use find to read them.
- EntryListResponse has two getters:
- getEntries() returns a List<EntryPojo>.
- getRawJson() returns each entry as a Gson JsonObject.
- Each EntryPojo has the public fields title, uid, version, and locale. getFields() returns the other fields as a Map<String, Object>, without the system fields tags, ACL, created_by, updated_by, created_at, updated_at, and _in_progress.
- getStringField(key) returns a field as a String, and getJsonObjectField(key) returns a Group or other object field as a Map<String, Object>.
Example
Basic usage: print the title and version of each entry
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import com.contentstack.cms.stack.EntryListResponse;
import com.contentstack.cms.stack.EntryPojo;
import retrofit2.Response;
import java.io.IOException;
public class FindEntriesAsPojo {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry();
Response<EntryListResponse> response = entry.findAsPojo().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
for (EntryPojo item : response.body().getEntries()) {
System.out.println(item.uid + " " + item.title + " v" + item.version);
System.out.println("url: " + item.getStringField("url"));
}
}
}getLanguage
getLanguage lists the locales that an entry exists in.
Returns: Call<ResponseBody>. The request for the entry's locales, sent when you call execute().
Validation
- Throws NullPointerException if the entry UID is null, as after entry(null), because the request path needs the entry UID.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One call builds one Get languages of an entry request (GET /content_types/{content_type_uid}/entries/{entry_uid}/locales).
- The request sends the query parameters of this entry. The API reference lists no query parameters for this request.
Example
Basic usage: list the locales of an entry
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class GetEntryLocales {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry("<ENTRY_UID>");
Response<ResponseBody> response = entry.getLanguage().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}getReference
getReference lists the entries and content types that reference an entry, so that you can see where the entry is in use.
Returns: Call<ResponseBody>. The request for the entries that reference this entry, sent when you call execute().
Validation
- Throws NullPointerException if the entry UID is null, as after entry(null), because the request path needs the entry UID.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One call builds one Get references of an entry request (GET /content_types/{content_type_uid}/entries/{entry_uid}/references).
- The request sends the query parameters of this entry. The API accepts the following three, among others:
- locale selects the locale. Without it, the API uses the master locale.
- include_publish_details set to true adds the version name, version number, and publish details of each referencing entry.
- include_branch adds the _branch key.
Example
Basic usage: list the entries that reference an entry
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class GetEntryReferences {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry("<ENTRY_UID>");
Response<ResponseBody> response = entry.getReference().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}Query parameters: include publish details for one locale
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class GetEntryReferencesWithDetails {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry("<ENTRY_UID>")
.addParam("locale", "<LOCALE>")
.addParam("include_publish_details", true);
Response<ResponseBody> response = entry.getReference().execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}importExisting
importExisting builds an Import an existing entry request, which imports a new version of an entry.
Returns: Call<ResponseBody>. The request for the existing-entry import, sent when you call execute().
Validation
- Throws NullPointerException if the entry UID is null, as after entry(null), because the request path needs the entry UID.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One call builds one POST /content_types/{content_type_uid}/entries/{entry_uid}/import request with an empty body.
- The request sends the query parameters of this entry. The API accepts locale for the language of the import and overwrite set to true to replace the existing entry.
Example
Basic usage: build the import request for an existing entry
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class ImportExistingEntry {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry("<ENTRY_UID>")
.addParam("locale", "<LOCALE>")
.addParam("overwrite", true);
Response<ResponseBody> response = entry.importExisting().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}imports
imports builds an Import an entry request for the content type.
Returns: Call<ResponseBody>. The request for the entry import, sent when you call execute().
Validation
- There is no client-side validation.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One call builds one POST /content_types/{content_type_uid}/entries/import request with an empty body.
- The request sends the query parameters of this entry. The API accepts locale for the language of the import and overwrite set to true to replace an existing entry.
- imports ignores the entry UID. To import a new version of an existing entry, see the importExisting method.
Example
Basic usage: build the import request with its query parameters
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class ImportEntry {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry()
.addParam("locale", "<LOCALE>")
.addParam("overwrite", false);
Response<ResponseBody> response = entry.imports().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}includeReference
includeReference lists the entries of the content type and asks for the entries in the reference fields you name.
| Name | Type | Description |
|---|---|---|
| referenceField (required) | Object | A String or String[] of reference field UIDs. |
Returns: Call<ResponseBody>. The request for all entries of the content type and their referenced entries, sent when you call execute().
Validation
- Throws IllegalArgumentException if referenceField is not a String or a String[], including null, because the SDK sends only those two types.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One call builds one Get all entries request (GET /content_types/{content_type_uid}/entries), with the query parameters of this entry.
- includeReference sends Get all entries even on an entry with a UID. It never reads a single entry.
- The SDK adds the field UIDs to the query parameter map of this entry in one of the following two ways:
- A String becomes one include[] parameter. A later String call replaces it.
- A String[] becomes numbered parameters, one per field: include[]1, include[]2, and so on. The numbers continue across calls on the same entry.
- The parameters stay in the map, so later requests from this entry send them too. Remove one with removeParam.
Limitations
- Does not read a single entry with its references. To send the same parameter with a single-entry read, call addParam("include[]", "<field_uid>") and then fetch.
Example
Basic usage: list entries with one reference field
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class FindEntriesWithReference {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry();
Response<ResponseBody> response = entry.includeReference("author").execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}Several fields: pass a String array
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class FindEntriesWithReferences {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry()
.addParam("locale", "<LOCALE>");
// Sends include[]1=author&include[]2=related_posts
String[] fields = {"author", "related_posts"};
Response<ResponseBody> response = entry.includeReference(fields).execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}localize
localize creates the localized version of an entry in one locale, so that the entry stops reading the content of its fallback language there.
| Name | Type | Description |
|---|---|---|
| requestBody (required) | JSONObject | Request body with the localized content under an entry key. |
| requestBody.entry (required) | JSONObject | Field UIDs mapped to the values for the locale. |
| localeCode (required) | String | Code of the locale to localize the entry in, such as fr-fr. |
Returns: Call<ResponseBody>. The request for the localized entry, sent when you call execute().
Validation
- Throws NullPointerException if the entry UID is null, as after entry(null), because the request path needs the entry UID.
- A null body makes execute() throw IllegalArgumentException, because Retrofit cannot build a request without a body.
- A null localeCode does not throw. The SDK then sends no locale parameter, and the request matches Update an entry without a locale.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One call builds one Localize an entry request (PUT /content_types/{content_type_uid}/entries/{entry_uid}?locale={locale_code}) with requestBody as the JSON body.
- Note the argument order: the body comes first and the locale second.
- localize sends only the locale parameter. Values from addParam do not reach this request.
- When a Group, Modular Blocks, or Global field instance contains a field marked non-localizable, include _metadata.uid for that field in the body, as Localize an entry states.
- The API does not publish the localized version. Publish it with publish and the locale.
- To change a localized version later, call localize again, or follow Update a localized entry. unLocalize reverses the localization.
Example
Basic usage: localize an entry in French
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class LocalizeEntry {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry("<ENTRY_UID>");
JSONObject fields = new JSONObject();
fields.put("title", "Article de blog");
fields.put("url", "/fr/article-de-blog");
JSONObject body = new JSONObject();
body.put("entry", fields);
Response<ResponseBody> response = entry.localize(body, "fr-fr").execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}publish
publish publishes an entry to the environments and locales you name, at once or at a scheduled time.
| Name | Type | Description |
|---|---|---|
| requestBody (required) | JSONObject | Request body with the publish details under an entry key. |
| requestBody.entry.environments (required) | JSONArray | Names of the environments to publish to. |
| requestBody.entry.locales | JSONArray | Codes of the locales to publish. |
| requestBody.locale | String | Locale of the entry version to publish. |
| requestBody.version | int | Version number of the entry to publish. |
Returns: Call<ResponseBody>. The request for the entry publish, sent when you call execute().
Validation
- Throws NullPointerException if the entry UID is null, as after entry(null), because the request path needs the entry UID.
- A null body makes execute() throw IllegalArgumentException, because Retrofit cannot build a request without a body.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One call builds one Publish an entry request (POST /content_types/{content_type_uid}/entries/{entry_uid}/publish) with requestBody as the JSON body, and with the query parameters of this entry.
- The API also publishes the metadata that the entry carries, as Publish an entry states.
- Locales in the body behave in one of the following two ways:
- For a locale where the entry has no localized version, the API localizes the master locale content in that locale and publishes it.
- For a locale where the entry has a localized version, the API does not publish that localized content. Use a bulk publish for that.
- publish adds no api_version header. Publish an entry lists api_version for nested reference publishing. Add it with addHeader.
- To publish entry variants, use publishEntryVariants, which sends the same request with api_version set to 3.2. To publish the entry with its references, see the publishWithReference method.
Example
Basic usage: publish an entry to one environment
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import org.json.simple.JSONArray;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class PublishEntry {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry("<ENTRY_UID>");
JSONArray environments = new JSONArray();
environments.add("<ENVIRONMENT>");
JSONObject details = new JSONObject();
details.put("environments", environments);
JSONObject body = new JSONObject();
body.put("entry", details);
Response<ResponseBody> response = entry.publish(body).execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}All body keys: publish version 2 in two locales
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import org.json.simple.JSONArray;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class PublishEntryVersion {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry("<ENTRY_UID>");
JSONArray environments = new JSONArray();
environments.add("<ENVIRONMENT>");
JSONArray locales = new JSONArray();
locales.add("en-us");
locales.add("fr-fr");
JSONObject details = new JSONObject();
details.put("environments", environments);
details.put("locales", locales);
JSONObject body = new JSONObject();
body.put("entry", details);
body.put("locale", "en-us");
body.put("version", 2);
Response<ResponseBody> response = entry.publish(body).execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}publishEntryVariants
publishEntryVariants publishes variants of an entry to the environments and locales you name.
| Name | Type | Description |
|---|---|---|
| requestBody (required) | JSONObject | Request body with the publish details under an entry key. |
| requestBody.entry.environments (required) | JSONArray | Names of the environments to publish to. |
| requestBody.entry.locales | JSONArray | Codes of the locales to publish. |
| requestBody.entry.variants (required) | JSONArray | Variants to publish, each with uid and version. |
| requestBody.entry.variant_rules.publish_latest_base_conditionally | Boolean | Set true to publish the latest base entry with the variant when needed. |
| requestBody.locale | String | Locale of the entry. |
Returns: Call<ResponseBody>. The request for the entry variant publish, sent when you call execute().
Validation
- Throws NullPointerException if the entry UID is null, as after entry(null), because the request path needs the entry UID.
- A null body makes execute() throw IllegalArgumentException, because Retrofit cannot build a request without a body.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One call builds one Publish entry variant request (POST /content_types/{content_type_uid}/entries/{entry_uid}/publish) with requestBody as the JSON body. This is the path of publish.
- The SDK adds the header api_version: 3.2 to this request. When the entry already holds an api_version header from addHeader, the SDK keeps that value.
- The SDK adds the header to a copy of the entry headers, so later requests from the entry do not carry it.
- The request sends the query parameters of this entry. The API accepts locale.
- The request sends the branch header of this entry: the stack branch, or the one from addBranch.
- You do not need the base entry version in the body. The API publishes the variant on the latest base version, or as variant_rules sets, and ignores a base version you include.
Example
Basic usage: publish one variant to one environment
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import org.json.simple.JSONArray;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class PublishEntryVariant {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry("<ENTRY_UID>")
.addParam("locale", "<LOCALE>");
JSONObject variant = new JSONObject();
variant.put("uid", "<VARIANT_UID>");
variant.put("version", 1);
JSONArray variants = new JSONArray();
variants.add(variant);
JSONObject rules = new JSONObject();
rules.put("publish_latest_base_conditionally", true);
JSONArray environments = new JSONArray();
environments.add("<ENVIRONMENT>");
JSONArray locales = new JSONArray();
locales.add("<LOCALE>");
JSONObject details = new JSONObject();
details.put("environments", environments);
details.put("locales", locales);
details.put("variants", variants);
details.put("variant_rules", rules);
JSONObject body = new JSONObject();
body.put("entry", details);
body.put("locale", "<LOCALE>");
Response<ResponseBody> response = entry.publishEntryVariants(body).execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}publishRequest
publishRequest sends a publish request for an entry, or approves or rejects one that the entry received, under a publish rule.
| Name | Type | Description |
|---|---|---|
| publishing_rule (required) | JSONObject | Request body with the rule under workflow.publishing_rule. |
| publishing_rule.workflow.publishing_rule.uid (required) | String | UID of the publish rule. |
| publishing_rule.workflow.publishing_rule.action (required) | String | publish, unpublish, or both. |
| publishing_rule.workflow.publishing_rule.status (required) | int | 0 requests approval, 1 approves, -1 rejects. |
| publishing_rule.workflow.publishing_rule.notify | Boolean | Set true to notify the approver. |
| publishing_rule.workflow.publishing_rule.comment | String | Comment for the approver. |
Returns: Call<ResponseBody>. The request for the publish approval action, sent when you call execute().
Validation
- Throws NullPointerException if the entry UID is null, as after entry(null), because the request path needs the entry UID.
- A null body makes execute() throw IllegalArgumentException, because Retrofit cannot build a request without a body.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One call builds one Request, accept, or reject an entry publish request request (POST /content_types/{content_type_uid}/entries/{entry_uid}/workflow) with publishing_rule as the JSON body.
- The request sends the query parameters of this entry. The API accepts locale for the locale of the entry.
- The API reference for this request lists the api_key and authtoken headers.
- setWorkflowStage sends a request to the same path with a workflow stage in the body.
Example
Basic usage: approve a publish request
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class ApprovePublishRequest {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry("<ENTRY_UID>")
.addParam("locale", "<LOCALE>");
JSONObject rule = new JSONObject();
rule.put("uid", "<PUBLISH_RULE_UID>");
rule.put("action", "publish");
rule.put("status", 1);
rule.put("notify", true);
rule.put("comment", "Approved for launch");
JSONObject workflow = new JSONObject();
workflow.put("publishing_rule", rule);
JSONObject body = new JSONObject();
body.put("workflow", workflow);
Response<ResponseBody> response = entry.publishRequest(body).execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}publishWithReference
publishWithReference publishes an entry together with the entries it references, in one request.
| Name | Type | Description |
|---|---|---|
| requestBody (required) | JSONObject | Request body that names the entries, locales, and environments. |
| requestBody.entries (required) | JSONArray | The main entry: its UID, content type UID, locale, and version. |
| requestBody.locales (required) | JSONArray | Codes of the locales to publish. |
| requestBody.environments (required) | JSONArray | Names of the environments to publish to. |
| requestBody.publish_with_reference | Boolean | Set true to publish the referenced entries too. |
Returns: Call<ResponseBody>. The request for the publish of the entry and its references, sent when you call execute().
Validation
- There is no client-side validation. publishWithReference does not read the entry UID, so it works on any entry object.
- A null body makes execute() throw IllegalArgumentException, because Retrofit cannot build a request without a body.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One call builds one Publish an entry with references request (POST /bulk/publish?x-bulk-action=publish) with requestBody as the JSON body.
- The body names the entry to publish. The content type and entry UID of this Entry object do not reach the request.
- The request sends the query parameters of this entry. The API accepts the following two:
- approvals set to true publishes the entries that do not need an approval.
- skip_workflow_stage_check set to true publishes the entries whose workflow stage satisfies the publish rules.
- One request publishes an entry in up to 50 locales and to up to 10 environments, as Publish an entry with references states.
Example
Basic usage: publish an entry and its references
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import org.json.simple.JSONArray;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class PublishEntryWithReferences {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry();
JSONObject mainEntry = new JSONObject();
mainEntry.put("uid", "<ENTRY_UID>");
mainEntry.put("content_type", "<CONTENT_TYPE_UID>");
mainEntry.put("locale", "<LOCALE>");
mainEntry.put("version", 1);
JSONArray entries = new JSONArray();
entries.add(mainEntry);
JSONArray locales = new JSONArray();
locales.add("<LOCALE>");
JSONArray environments = new JSONArray();
environments.add("<ENVIRONMENT>");
JSONObject body = new JSONObject();
body.put("entries", entries);
body.put("locales", locales);
body.put("environments", environments);
body.put("publish_with_reference", true);
Response<ResponseBody> response = entry.publishWithReference(body).execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}Query parameters: skip the approval and workflow checks
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import org.json.simple.JSONArray;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class PublishEntryWithReferencesSkipChecks {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry()
.addParam("approvals", true)
.addParam("skip_workflow_stage_check", true);
JSONObject mainEntry = new JSONObject();
mainEntry.put("uid", "<ENTRY_UID>");
mainEntry.put("content_type", "<CONTENT_TYPE_UID>");
mainEntry.put("locale", "<LOCALE>");
mainEntry.put("version", 1);
JSONArray entries = new JSONArray();
entries.add(mainEntry);
JSONArray locales = new JSONArray();
locales.add("<LOCALE>");
JSONArray environments = new JSONArray();
environments.add("<ENVIRONMENT>");
JSONObject body = new JSONObject();
body.put("entries", entries);
body.put("locales", locales);
body.put("environments", environments);
body.put("publish_with_reference", true);
Response<ResponseBody> response = entry.publishWithReference(body).execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}query
query lists the entries of the content type that match a JSON query, such as a taxonomy filter.
| Name | Type | Description |
|---|---|---|
| query (required) | JSONObject | Query conditions, sent as the query parameter. |
Returns: Call<ResponseBody>. The request for the entries that match the query, sent when you call execute().
Validation
- There is no client-side validation of the conditions.
- A null query does not throw. The SDK then sends no query parameter, and the request lists every entry of the content type.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One call builds one GET /content_types/{content_type_uid}/entries request, the path of Get all entries.
- The SDK writes query as JSON text into the query parameter and URL-encodes it.
- query sends no other query parameter. Values from addParam do not reach this request.
- query ignores the entry UID, so it works the same on entry() and on entry("<ENTRY_UID>").
Example
Basic usage: list entries tagged with either of two taxonomy terms
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import org.json.simple.JSONArray;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class QueryEntriesByTaxonomy {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry();
JSONArray terms = new JSONArray();
terms.add("<TERM_UID>");
terms.add("<TERM_UID>");
JSONObject in = new JSONObject();
in.put("$in", terms);
JSONObject query = new JSONObject();
query.put("taxonomies.<TAXONOMY_UID>", in);
Response<ResponseBody> response = entry.query(query).execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}removeParam
removeParam removes one query parameter from this entry, so that later requests no longer send it.
| Name | Type | Description |
|---|---|---|
| key (required) | String | Name of the query parameter to remove. |
Returns: Entry. The same entry, for chaining.
Validation
- There is no client-side validation. A key that the entry does not hold changes nothing and does not throw.
- An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Removes the key from the query parameter map that addParam, addParams, and includeReference fill.
- To remove the parameters that includeReference added for a String[], pass the numbered keys it created, such as include[]1.
- Headers are not query parameters. To send a request without a header, create a new entry object.
Example
Basic usage: drop the locale before the next request
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class RemoveLocaleParam {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry("<ENTRY_UID>")
.addParam("locale", "<LOCALE>");
Response<ResponseBody> localized = entry.fetch().execute();
if (!localized.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + localized.code() + " " + localized.errorBody().string());
return;
}
System.out.println(localized.body().string());
// The next request reads the master locale again
Response<ResponseBody> master = entry.removeParam("locale").fetch().execute();
if (!master.isSuccessful()) { System.out.println(master.errorBody().string()); return; }
System.out.println(master.body().string());
}
}setWorkflowStage
setWorkflowStage moves an entry to a workflow stage, or updates the stage details such as the assignee and due date.
| Name | Type | Description |
|---|---|---|
| workflow (required) | JSONObject | Request body with the stage under workflow.workflow_stage. |
| workflow.workflow.workflow_stage.uid (required) | String | UID of the workflow stage to set. |
| workflow.workflow.workflow_stage.comment | String | Comment for the assigned user. |
| workflow.workflow.workflow_stage.due_date | String | Due date for the stage. |
| workflow.workflow.workflow_stage.notify | Boolean | Set true to notify the assigned user. |
| workflow.workflow.workflow_stage.assigned_to | JSONArray | Users to assign, each with uid, name, and email. |
Returns: Call<ResponseBody>. The request for the workflow stage change, sent when you call execute().
Validation
- Throws NullPointerException if the entry UID is null, as after entry(null), because the request path needs the entry UID.
- A null body makes execute() throw IllegalArgumentException, because Retrofit cannot build a request without a body.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One call builds one Set entry workflow stage request (POST /content_types/{content_type_uid}/entries/{entry_uid}/workflow) with workflow as the JSON body.
- The request sends the query parameters of this entry. The API accepts locale to set the stage of one localized version.
- Set entry workflow stage lists the authtoken header as required for this request.
- publishRequest sends a request to the same path with a publish rule in the body.
Example
Basic usage: move an entry to a stage and assign a user
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import org.json.simple.JSONArray;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class SetEntryWorkflowStage {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry("<ENTRY_UID>")
.addParam("locale", "<LOCALE>");
JSONObject user = new JSONObject();
user.put("uid", "<USER_UID>");
user.put("name", "Jane Doe");
user.put("email", "<EMAIL>");
JSONArray assignedTo = new JSONArray();
assignedTo.add(user);
JSONObject stage = new JSONObject();
stage.put("uid", "<WORKFLOW_STAGE_UID>");
stage.put("comment", "Ready for review");
stage.put("due_date", "Thu Dec 01 2026");
stage.put("notify", true);
stage.put("assigned_to", assignedTo);
JSONObject workflow = new JSONObject();
workflow.put("workflow_stage", stage);
JSONObject body = new JSONObject();
body.put("workflow", workflow);
Response<ResponseBody> response = entry.setWorkflowStage(body).execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}unLocalize
unLocalize removes the localized version of an entry in one locale, so that the entry reads the content of its fallback language there again.
| Name | Type | Description |
|---|---|---|
| localeCode (required) | String | Code of the locale to unlocalize, such as fr-fr. |
Returns: Call<ResponseBody>. The request for the entry unlocalization, sent when you call execute().
Validation
- Throws NullPointerException if the entry UID is null, as after entry(null), because the request path needs the entry UID.
- A null localeCode does not throw. The SDK then sends no locale parameter, which the API requires.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One call builds one Unlocalize an entry request (POST /content_types/{content_type_uid}/entries/{entry_uid}/unlocalize?locale={locale_code}) with no body.
- unLocalize sends only the locale parameter. Values from addParam do not reach this request.
- localize creates a localized version again.
Example
Basic usage: unlocalize the French version of an entry
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class UnlocalizeEntry {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry("<ENTRY_UID>");
Response<ResponseBody> response = entry.unLocalize("fr-fr").execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}unpublish
unpublish removes a published entry from the environments and locales you name, at once or at a scheduled time.
| Name | Type | Description |
|---|---|---|
| requestBody (required) | JSONObject | Request body with the unpublish details under an entry key. |
| requestBody.entry.environments (required) | JSONArray | Names of the environments to unpublish from. |
| requestBody.entry.locales | JSONArray | Codes of the locales to unpublish. |
| requestBody.locale | String | Locale of the entry version to unpublish. |
| requestBody.version | int | Version number of the entry to unpublish. |
Returns: Call<ResponseBody>. The request for the entry unpublish, sent when you call execute().
Validation
- Throws NullPointerException if the entry UID is null, as after entry(null), because the request path needs the entry UID.
- A null body makes execute() throw IllegalArgumentException, because Retrofit cannot build a request without a body.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One call builds one Unpublish an entry request (POST /content_types/{content_type_uid}/entries/{entry_uid}/unpublish) with requestBody as the JSON body, and with the query parameters of this entry.
- Without locales in the body, the API unpublishes the entry from the master locale, as Unpublish an entry states.
- unpublish adds no api_version header. Add it with addHeader when you need it. To unpublish entry variants, use unpublishEntryVariants.
Example
Basic usage: unpublish an entry from one environment
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import org.json.simple.JSONArray;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class UnpublishEntry {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry("<ENTRY_UID>");
JSONArray environments = new JSONArray();
environments.add("<ENVIRONMENT>");
JSONObject details = new JSONObject();
details.put("environments", environments);
JSONObject body = new JSONObject();
body.put("entry", details);
Response<ResponseBody> response = entry.unpublish(body).execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}All body keys: unpublish version 2 from two locales
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import org.json.simple.JSONArray;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class UnpublishEntryVersion {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry("<ENTRY_UID>");
JSONArray environments = new JSONArray();
environments.add("<ENVIRONMENT>");
JSONArray locales = new JSONArray();
locales.add("en-us");
locales.add("fr-fr");
JSONObject details = new JSONObject();
details.put("environments", environments);
details.put("locales", locales);
JSONObject body = new JSONObject();
body.put("entry", details);
body.put("locale", "en-us");
body.put("version", 2);
Response<ResponseBody> response = entry.unpublish(body).execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}unpublishEntryVariants
unpublishEntryVariants removes published variants of an entry from the environments and locales you name.
| Name | Type | Description |
|---|---|---|
| requestBody (required) | JSONObject | Request body with the unpublish details under an entry key. |
| requestBody.entry.environments (required) | JSONArray | Names of the environments to unpublish from. |
| requestBody.entry.locales | JSONArray | Codes of the locales to unpublish. |
| requestBody.entry.variants (required) | JSONArray | Variants to unpublish, each with uid and version. |
| requestBody.locale | String | Locale of the entry. |
Returns: Call<ResponseBody>. The request for the entry variant unpublish, sent when you call execute().
Validation
- Throws NullPointerException if the entry UID is null, as after entry(null), because the request path needs the entry UID.
- A null body makes execute() throw IllegalArgumentException, because Retrofit cannot build a request without a body.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One call builds one Unpublish entry variant request (POST /content_types/{content_type_uid}/entries/{entry_uid}/unpublish) with requestBody as the JSON body. This is the path of unpublish.
- The SDK adds the header api_version: 3.2 to a copy of the entry headers for this request. When the entry already holds an api_version header, the SDK keeps that value.
- The request sends the query parameters of this entry. The API accepts locale.
- The request sends the branch header of this entry: the stack branch, or the one from addBranch.
Example
Basic usage: unpublish one variant from one environment
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import org.json.simple.JSONArray;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class UnpublishEntryVariant {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry("<ENTRY_UID>");
JSONObject variant = new JSONObject();
variant.put("uid", "<VARIANT_UID>");
variant.put("version", 1);
JSONArray variants = new JSONArray();
variants.add(variant);
JSONArray environments = new JSONArray();
environments.add("<ENVIRONMENT>");
JSONArray locales = new JSONArray();
locales.add("<LOCALE>");
JSONObject details = new JSONObject();
details.put("environments", environments);
details.put("locales", locales);
details.put("variants", variants);
JSONObject body = new JSONObject();
body.put("entry", details);
body.put("locale", "<LOCALE>");
Response<ResponseBody> response = entry.unpublishEntryVariants(body).execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}update
update changes the content of an existing entry.
| Name | Type | Description |
|---|---|---|
| requestBody (required) | JSONObject | Request body with the entry under an entry key. |
| requestBody.entry (required) | JSONObject | Field UIDs mapped to their new values. |
Returns: Call<ResponseBody>. The request for the updated entry, sent when you call execute().
Validation
- Throws NullPointerException if the entry UID is null, as after entry(null), because the request path needs the entry UID.
- A null body makes execute() throw IllegalArgumentException, because Retrofit cannot build a request without a body.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One call builds one Update an entry request (PUT /content_types/{content_type_uid}/entries/{entry_uid}) with requestBody as the JSON body.
- The request sends the query parameters of this entry. With a locale parameter, the API localizes the entry in that locale, as Update an entry states. localize sends the same request with the locale as an argument.
- The API does not publish the change. Publish the entry with publish.
Limitations
- Does not change the workflow stage of the entry. Use setWorkflowStage instead.
Example
Basic usage: change the title of an entry
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class UpdateEntry {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry("<ENTRY_UID>");
JSONObject fields = new JSONObject();
fields.put("title", "docs-test-blog-post-updated");
JSONObject body = new JSONObject();
body.put("entry", fields);
Response<ResponseBody> response = entry.update(body).execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}Locale: update the content of one localized version
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class UpdateLocalizedEntry {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry("<ENTRY_UID>")
.addParam("locale", "<LOCALE>");
JSONObject fields = new JSONObject();
fields.put("title", "docs-test-blog-post-localized");
JSONObject body = new JSONObject();
body.put("entry", fields);
Response<ResponseBody> response = entry.update(body).execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}updateEntryVariant
updateEntryVariant changes the fields of an existing variant of an entry.
| Name | Type | Description |
|---|---|---|
| variantUid (required) | String | UID of the variant. |
| requestBody (required) | JSONObject | Request body with the variant fields under an entry key. |
| requestBody.entry (required) | JSONObject | Field UIDs mapped to the values that differ from the base entry. |
Returns: Call<ResponseBody>. The request for the updated entry variant, sent when you call execute().
Validation
- Throws NullPointerException if the entry UID is null, as after entry(null), because the request path needs the entry UID.
- Throws NullPointerException if variantUid is null, and IllegalArgumentException if it is empty or only whitespace, because the request path needs the variant UID.
- A null body makes execute() throw IllegalArgumentException, because Retrofit cannot build a request without a body.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One call builds one Update entry variant request (PUT /content_types/{content_type_uid}/entries/{entry_uid}/variants/{variant_uid}) with requestBody as the JSON body.
- createEntryVariant sends the same request. The API creates the variant when it does not exist and updates it when it does.
- The request sends the query parameters of this entry. The API accepts locale for the language of the variant.
- The request sends the branch header of this entry: the stack branch, or the one from addBranch.
- Link the content type to a variant group before you call this method, as Update entry variant states. Fields you leave out keep the values of the base entry.
- For Group and Modular Blocks fields with several instances, the API reads the _order property to set the order of the instances.
Example
Basic usage: change the title and URL of a variant
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class UpdateEntryVariant {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry("<ENTRY_UID>")
.addParam("locale", "<LOCALE>");
JSONObject fields = new JSONObject();
fields.put("title", "docs-test-blue-variant-v2");
fields.put("url", "/docs-test-blue-variant-v2");
JSONObject body = new JSONObject();
body.put("entry", fields);
Response<ResponseBody> response = entry.updateEntryVariant("<VARIANT_UID>", body).execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}versionName
versionName assigns a name to one version of an entry, so that you can find that version again by name.
| Name | Type | Description |
|---|---|---|
| version (required) | int | Version number of the entry to name. |
| requestBody (required) | JSONObject | Request body with the name under an entry key. |
| requestBody.entry._version_name (required) | String | Name to assign to the version. |
| requestBody.entry.locale (required) | String | Locale of the entry version. |
| requestBody.entry.force | Boolean | Set true to replace a name that the version already has. |
Returns: Call<ResponseBody>. The request for the named entry version, sent when you call execute().
Validation
- Throws NullPointerException if the entry UID is null, as after entry(null), because the request path needs the entry UID.
- A null body makes execute() throw IllegalArgumentException, because Retrofit cannot build a request without a body.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One call builds one Set Version Name for Entry request (POST /content_types/{content_type_uid}/entries/{entry_uid}/versions/{version_number}/name) with requestBody as the JSON body.
- versionName sends no query parameters. Values from addParam do not reach this request.
- detailOfAllVersion lists the names, and deleteVersionName removes one.
Example
Basic usage: name version 3 of an entry
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class NameEntryVersion {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry("<ENTRY_UID>");
JSONObject details = new JSONObject();
details.put("_version_name", "Spring launch copy");
details.put("locale", "<LOCALE>");
JSONObject body = new JSONObject();
body.put("entry", details);
Response<ResponseBody> response = entry.versionName(3, body).execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}Edge case: replace the existing name of a version
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class RenameEntryVersion {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry("<ENTRY_UID>");
JSONObject details = new JSONObject();
details.put("_version_name", "Final approved copy");
details.put("locale", "<LOCALE>");
details.put("force", true);
JSONObject body = new JSONObject();
body.put("entry", details);
Response<ResponseBody> response = entry.versionName(3, body).execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}withAppliedVariantUid
withAppliedVariantUid adds the x-cs-variant-uid header to the requests of this entry, so that fetch and fetchAsPojo ask for the base entry merged with that variant.
| Name | Type | Description |
|---|---|---|
| variantUid (required) | String | UID of the variant to apply. |
Returns: Entry. The same entry, for chaining.
Validation
- Throws NullPointerException if variantUid is null, and IllegalArgumentException if it is empty or only whitespace, because the header needs a variant UID.
- There is no other client-side validation.
- An unknown variant surfaces as an API error in the response when you call execute() on the request this method feeds.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Puts the header into the header map of this entry. It replaces an earlier variant UID on the same entry.
- The header stays on the entry, and every later request from it sends the header, not only fetch. Create a new entry object for requests that must not carry it.
- The header is separate from the branch. Set the branch with addBranch.
- To read the variant itself rather than the base entry merged with it, use fetchEntryVariant.
Example
Basic usage: read an entry merged with one variant
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Entry;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class FetchEntryWithVariant {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Entry entry = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.contentType("<CONTENT_TYPE_UID>")
.entry("<ENTRY_UID>")
.withAppliedVariantUid("<VARIANT_UID>");
Response<ResponseBody> response = entry.fetch().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}