Entry

View as Markdown

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:

NameTypeDescription
contentTypeUidStringUID of the content type. Pass it to stack.contentType().
entryUidStringUID 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.

NameTypeDescription
branchUid (required)String

UID or alias of the branch to target.

Default: Not applicable

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.

NameTypeDescription
key (required)String

Name of the header, such as api_version.

Default: Not applicable
value (required)String

Value of the header.

Default: Not applicable

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.

NameTypeDescription
headers (required)HashMap<String, String>

Header names mapped to their values.

Default: Not applicable

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.

NameTypeDescription
key (required)String

Name of the query parameter, such as locale.

Default: Not applicable
value (required)Object

Value of the parameter. The SDK sends its toString() form.

Default: Not applicable

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.

NameTypeDescription
params (required)HashMap<String, Object>

Parameter names mapped to their values.

Default: Not applicable

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.

NameTypeDescription
requestBody (required)JSONObject

Request body with the operations under an entry key.

Default: Not applicable
requestBody.entry (required)JSONObject

Field UIDs mapped to one operator object each.

Default: Not applicable

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.

NameTypeDescription
requestBody (required)JSONObject

Request body with the entry under an entry key.

Default: Not applicable
requestBody.entry (required)JSONObject

Field UIDs mapped to their values, such as title and url.

Default: Not applicable

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.

NameTypeDescription
variantUid (required)String

UID of the variant.

Default: Not applicable
requestBody (required)JSONObject

Request body with the variant fields under an entry key.

Default: Not applicable
requestBody.entry (required)JSONObject

Field UIDs mapped to the values that differ from the base entry.

Default: Not applicable

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.

NameTypeDescription
requestBody (required)JSONObject

Request body that names the localized versions to delete.

Default: Not applicable
requestBody.entry.locales (required)JSONArray

Locale codes of the localized versions to delete.

Default: Not applicable

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.

NameTypeDescription
variantUid (required)String

UID of the variant to delete.

Default: Not applicable

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.

NameTypeDescription
versionNumber (required)int

Version number whose name to remove.

Default: Not applicable
requestBody (required)JSONObject

Request body with the locale under an entry key.

Default: Not applicable
requestBody.entry.localeString

Locale of the entry version.

Default: API default

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.

NameTypeDescription
variantUid (required)String

UID of the variant to read.

Default: Not applicable
branchUid (required)String

Branch for this request only. null or blank keeps the entry's branch.

Default: Not applicable

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.

NameTypeDescription
referenceField (required)Object

A String or String[] of reference field UIDs.

Default: Not applicable

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.

NameTypeDescription
requestBody (required)JSONObject

Request body with the localized content under an entry key.

Default: Not applicable
requestBody.entry (required)JSONObject

Field UIDs mapped to the values for the locale.

Default: Not applicable
localeCode (required)String

Code of the locale to localize the entry in, such as fr-fr.

Default: Not applicable

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.

NameTypeDescription
requestBody (required)JSONObject

Request body with the publish details under an entry key.

Default: Not applicable
requestBody.entry.environments (required)JSONArray

Names of the environments to publish to.

Default: Not applicable
requestBody.entry.localesJSONArray

Codes of the locales to publish.

Default: API default (master locale)
requestBody.localeString

Locale of the entry version to publish.

Default: API default
requestBody.versionint

Version number of the entry to publish.

Default: API default

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.

NameTypeDescription
requestBody (required)JSONObject

Request body with the publish details under an entry key.

Default: Not applicable
requestBody.entry.environments (required)JSONArray

Names of the environments to publish to.

Default: Not applicable
requestBody.entry.localesJSONArray

Codes of the locales to publish.

Default: API default (master locale)
requestBody.entry.variants (required)JSONArray

Variants to publish, each with uid and version.

Default: Not applicable
requestBody.entry.variant_rules.publish_latest_base_conditionallyBoolean

Set true to publish the latest base entry with the variant when needed.

Default: API default
requestBody.localeString

Locale of the entry.

Default: API default

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.

NameTypeDescription
publishing_rule (required)JSONObject

Request body with the rule under workflow.publishing_rule.

Default: Not applicable
publishing_rule.workflow.publishing_rule.uid (required)String

UID of the publish rule.

Default: Not applicable
publishing_rule.workflow.publishing_rule.action (required)String

publish, unpublish, or both.

Default: Not applicable
publishing_rule.workflow.publishing_rule.status (required)int

0 requests approval, 1 approves, -1 rejects.

Default: Not applicable
publishing_rule.workflow.publishing_rule.notifyBoolean

Set true to notify the approver.

Default: API default
publishing_rule.workflow.publishing_rule.commentString

Comment for the approver.

Default: API default

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.

NameTypeDescription
requestBody (required)JSONObject

Request body that names the entries, locales, and environments.

Default: Not applicable
requestBody.entries (required)JSONArray

The main entry: its UID, content type UID, locale, and version.

Default: Not applicable
requestBody.locales (required)JSONArray

Codes of the locales to publish.

Default: Not applicable
requestBody.environments (required)JSONArray

Names of the environments to publish to.

Default: Not applicable
requestBody.publish_with_referenceBoolean

Set true to publish the referenced entries too.

Default: API default

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.

NameTypeDescription
query (required)JSONObject

Query conditions, sent as the query parameter.

Default: Not applicable

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.

NameTypeDescription
key (required)String

Name of the query parameter to remove.

Default: Not applicable

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.

NameTypeDescription
workflow (required)JSONObject

Request body with the stage under workflow.workflow_stage.

Default: Not applicable
workflow.workflow.workflow_stage.uid (required)String

UID of the workflow stage to set.

Default: Not applicable
workflow.workflow.workflow_stage.commentString

Comment for the assigned user.

Default: API default
workflow.workflow.workflow_stage.due_dateString

Due date for the stage.

Default: API default
workflow.workflow.workflow_stage.notifyBoolean

Set true to notify the assigned user.

Default: API default
workflow.workflow.workflow_stage.assigned_toJSONArray

Users to assign, each with uid, name, and email.

Default: API default

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.

NameTypeDescription
localeCode (required)String

Code of the locale to unlocalize, such as fr-fr.

Default: Not applicable

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.

NameTypeDescription
requestBody (required)JSONObject

Request body with the unpublish details under an entry key.

Default: Not applicable
requestBody.entry.environments (required)JSONArray

Names of the environments to unpublish from.

Default: Not applicable
requestBody.entry.localesJSONArray

Codes of the locales to unpublish.

Default: API default (master locale)
requestBody.localeString

Locale of the entry version to unpublish.

Default: API default
requestBody.versionint

Version number of the entry to unpublish.

Default: API default

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.

NameTypeDescription
requestBody (required)JSONObject

Request body with the unpublish details under an entry key.

Default: Not applicable
requestBody.entry.environments (required)JSONArray

Names of the environments to unpublish from.

Default: Not applicable
requestBody.entry.localesJSONArray

Codes of the locales to unpublish.

Default: API default (master locale)
requestBody.entry.variants (required)JSONArray

Variants to unpublish, each with uid and version.

Default: Not applicable
requestBody.localeString

Locale of the entry.

Default: API default

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.

NameTypeDescription
requestBody (required)JSONObject

Request body with the entry under an entry key.

Default: Not applicable
requestBody.entry (required)JSONObject

Field UIDs mapped to their new values.

Default: Not applicable

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

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.

NameTypeDescription
variantUid (required)String

UID of the variant.

Default: Not applicable
requestBody (required)JSONObject

Request body with the variant fields under an entry key.

Default: Not applicable
requestBody.entry (required)JSONObject

Field UIDs mapped to the values that differ from the base entry.

Default: Not applicable

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.

NameTypeDescription
version (required)int

Version number of the entry to name.

Default: Not applicable
requestBody (required)JSONObject

Request body with the name under an entry key.

Default: Not applicable
requestBody.entry._version_name (required)String

Name to assign to the version.

Default: Not applicable
requestBody.entry.locale (required)String

Locale of the entry version.

Default: Not applicable
requestBody.entry.forceBoolean

Set true to replace a name that the version already has.

Default: API default

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

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.

NameTypeDescription
variantUid (required)String

UID of the variant to apply.

Default: Not applicable

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());
    }
}