Stack

View as Markdown

Stack

A Stack holds the API key and credentials of one stack and creates the objects that manage its content. Every stack-level request in the Java Management SDK starts from it.

Use this class to

  • open the modules of a stack, such as content types, assets, environments, tokens or releases
  • fetch the details of one stack, or list every stack you can access
  • create a stack, or update its name and description
  • read and change the stack settings
  • share the stack with a collaborator, change user roles, or transfer its ownership

acceptOwnership

acceptOwnership builds the request that accepts an invitation to take ownership of a stack.

NameTypeDescription
ownershipToken (required)String

Ownership token from the invitation email.

Default: Not applicable

Returns: Call<ResponseBody>. The request for the ownership acceptance, sent when you call execute().

Validation

  • There is no client-side validation. acceptOwnership does not check ownershipToken or the query parameters.
  • An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
  • The API rejects the request without the api_key and uid query parameters, because Accept stack owned by other user requires both.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • One execute() sends one Accept stack owned by other user request (GET /stacks/accept_ownership/{ownership_token}) with the stack's headers and its query parameters.
  • acceptOwnership does not add the API key or user UID to the query. Add them with addParam as api_key and uid, the values from the invitation link.
  • ownershipToken goes into the request path.

Example

Basic usage: accept an ownership invitation

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class AcceptStackOwnership {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        client.login("<EMAIL>", "<PASSWORD>");
        Stack stack = client.stack("<API_KEY>")
                .addParam("api_key", "<API_KEY>")
                .addParam("uid", "<USER_UID>");

        Response<ResponseBody> response = stack.acceptOwnership("<OWNERSHIP_TOKEN>").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());
    }
}

addHeader

addHeader adds one request header to the stack, for the stack's own requests and for the objects that its factory methods create afterwards.

NameTypeDescription
key (required)String

Name of the header, for example organization_uid.

Default: Not applicable
value (required)String

Value to send in the header.

Default: Not applicable

Returns: Stack. The same stack, for chaining.

Validation

  • There is no client-side validation.
  • 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

  • Client-side only. addHeader stores the pair in the stack's header map and sends no request.
  • A second call with the same key replaces the value. This includes the headers that client.stack(...) set, such as api_key, authorization and branch.
  • Every stack request except create sends the header map. create sends only the organization_uid header that it takes as an argument.
  • A factory method, such as contentType or environment, copies the header map when you call it. Add the header before you call the factory method, because objects created earlier do not receive it. The tokens object is the exception and always reads the stack's current headers.

Example

Basic usage: send the organization UID for a single sign-on (SSO) organization

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class FetchSsoStack {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        client.login("<EMAIL>", "<PASSWORD>");
        Stack stack = client.stack("<API_KEY>").addHeader("organization_uid", "<ORGANIZATION_UID>");

        Response<ResponseBody> response = stack.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());
    }
}

Add a branch header before you open a module

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class ListBranchContentTypes {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").addHeader("branch", "<BRANCH>");

        // contentType() copies the headers now, so it sends the branch header
        Response<ResponseBody> response = stack.contentType().find().execute();
        if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
        System.out.println(response.body().string());
    }
}

addHeaders

addHeaders adds several request headers to the stack in one call.

NameTypeDescription
headers (required)HashMap<String, String>

Header names mapped to their values.

Default: Not applicable

Returns: Stack. The same stack, for chaining.

Validation

  • There is no client-side validation.
  • 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

  • Client-side only. addHeaders copies every entry of headers into the stack's header map and sends no request.
  • An entry replaces an existing header with the same name.
  • The headers reach the same requests as a header from addHeader: every stack request except create, and the objects that factory methods create after the call.

Example

Basic usage: add the organization UID and a branch

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;
import java.util.HashMap;

public class AddStackHeaders {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        client.login("<EMAIL>", "<PASSWORD>");

        HashMap<String, String> headers = new HashMap<>();
        headers.put("organization_uid", "<ORGANIZATION_UID>");
        headers.put("branch", "<BRANCH>");
        Stack stack = client.stack("<API_KEY>").addHeaders(headers);

        Response<ResponseBody> response = stack.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());
    }
}

addParam

addParam adds one query parameter to the stack, for the find and acceptOwnership requests.

NameTypeDescription
key (required)String

Name of the query parameter, for example include_count.

Default: Not applicable
value (required)Object

Value of the query parameter, for example true.

Default: Not applicable

Returns: Stack. The same stack, for chaining.

Validation

  • There is no client-side validation.
  • 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

  • Client-side only. addParam stores the pair in the stack's query parameter map and sends no request.
  • A second call with the same key replaces the value.
  • Only find and acceptOwnership send the map. The other stack requests, such as update and share, send no query parameters.
  • The objects that the factory methods return, such as a content type or an environment, keep their own query parameters. A parameter on the stack does not reach them.
  • The parameter stays on the stack for every later find or acceptOwnership call. Use the removeParam method to drop it.
  • The API reference lists the parameters each request accepts. For example, Get all stacks accepts include_collaborators, include_stack_variables, include_discrete_variables and include_count.

Example

Basic usage: count the stacks you can access

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class CountStacks {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        client.login("<EMAIL>", "<PASSWORD>");
        Stack stack = client.stack().addParam("include_count", true);

        Response<ResponseBody> response = stack.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());
    }
}

Chain several parameters: include the collaborators and stack variables

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class FetchStackWithCollaborators {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        client.login("<EMAIL>", "<PASSWORD>");
        Stack stack = client.stack("<API_KEY>")
                .addParam("include_collaborators", true)
                .addParam("include_stack_variables", true);

        Response<ResponseBody> response = stack.find().execute();
        if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
        System.out.println(response.body().string());
    }
}

addParams

addParams adds several query parameters to the stack in one call, for the find and acceptOwnership requests.

NameTypeDescription
params (required)HashMap<String, Object>

Parameter names mapped to their values.

Default: Not applicable

Returns: Stack. The same stack, for chaining.

Validation

  • There is no client-side validation.
  • 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

  • Client-side only. addParams copies every entry of params into the stack's query parameter map and sends no request.
  • An entry replaces an existing parameter with the same name.
  • Only find and acceptOwnership send the map, as with addParam. Factory methods do not copy it.

Example

Basic usage: list every stack with its collaborators and a count

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;
import java.util.HashMap;

public class ListStacksWithCount {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        client.login("<EMAIL>", "<PASSWORD>");

        HashMap<String, Object> params = new HashMap<>();
        params.put("include_collaborators", true);
        params.put("include_count", true);
        Stack stack = client.stack().addParams(params);

        Response<ResponseBody> response = stack.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());
    }
}

alias

alias creates an Alias object for one branch alias, or for all the branch aliases of the stack.

NameTypeDescription
aliasUid (required)String

UID of the branch alias to open.

Default: Not applicable

Returns: Alias. A new alias object.

Overloads

  • alias(String aliasUid)
  • alias(): This overload takes no parameters. Use it for the requests that act on all branch aliases, such as find.

Validation

  • There is no client-side validation. alias accepts null and an empty string.
  • Errors come from the request method you call on the result, not from alias().
    • Methods that act on one branch alias, such as fetch, need the object from alias(String aliasUid). The Alias page states what each of them does without a UID.
    • An unknown UID does not throw. The API rejects the request, 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

  • Client-side only. alias sends no request.
  • Each call returns a new Alias. The new object copies the stack's headers, such as api_key, authorization and branch, when you call alias. A header you add to the stack later does not reach it.
  • The stack's query parameters do not reach the new object. Add them to the Alias object instead.

Example

Basic usage: fetch one branch alias by its UID

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Alias;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class FetchAlias {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");

        Alias alias = stack.alias("<ALIAS_UID>");
        Response<ResponseBody> response = alias.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());
    }
}

List every branch alias of the stack

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class ListAliases {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");

        Response<ResponseBody> response = stack.alias().find().execute();
        if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
        System.out.println(response.body().string());
    }
}

allUsers

allUsers builds the request that fetches the stack together with its collaborators.

Returns: Call<ResponseBody>. The request for the stack with its collaborators, 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().
  • The API rejects the request when the client has no authtoken, because Get a single stack requires one.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • One execute() sends one Get a single stack request (GET /stacks?include_collaborators=true) with the stack's headers.
  • allUsers does not call Get all users of a stack (GET /stacks/users). The users are in the collaborator details of the stack in the response.
  • allUsers always sends include_collaborators=true and no other query parameter. Values from addParam do not reach this request.
  • A stack from client.stack() sends no api_key header, so the API returns every stack you can access, each with its collaborators.
  • The response body is the raw JSON that the API returns. Read it once with response.body().string().

Example

Basic usage: list the collaborators of the stack

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class ListStackUsers {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        client.login("<EMAIL>", "<PASSWORD>");
        Stack stack = client.stack("<API_KEY>");

        Response<ResponseBody> response = stack.allUsers().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());
    }
}

asset

asset creates an Asset object for one asset, or for all the assets of the stack.

NameTypeDescription
assetUid (required)String

UID of the asset to open.

Default: Not applicable

Returns: Asset. A new asset object.

Overloads

  • asset(String assetUid)
  • asset(): This overload takes no parameters. Use it for the requests that act on all assets, such as find.

Validation

  • There is no client-side validation. asset accepts null and an empty string.
  • Errors come from the request method you call on the result, not from asset().
    • Methods that act on one asset, such as fetch, need the object from asset(String assetUid). The Asset page states what each of them does without a UID.
    • An unknown UID does not throw. The API rejects the request, 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

  • Client-side only. asset sends no request.
  • Each call returns a new Asset. The new object copies the stack's headers, such as api_key, authorization and branch, when you call asset. A header you add to the stack later does not reach it.
  • The stack's query parameters do not reach the new object. Add them to the Asset object instead.
  • Call folder() or folder("<FOLDER_UID>") on the result to manage asset folders.

Example

Basic usage: fetch one asset by its UID

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Asset;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class FetchAsset {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");

        Asset asset = stack.asset("<ASSET_UID>");
        Response<ResponseBody> response = asset.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());
    }
}

List every asset of the stack

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class ListAssets {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");

        Response<ResponseBody> response = stack.asset().find().execute();
        if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
        System.out.println(response.body().string());
    }
}

auditLog

auditLog creates an AuditLog object for one audit log item, or for all the audit log items of the stack.

NameTypeDescription
logItemUid (required)String

UID of the audit log item to open.

Default: Not applicable

Returns: AuditLog. A new audit log object.

Overloads

  • auditLog(String logItemUid)
  • auditLog(): This overload takes no parameters. Use it for the requests that act on all audit log items, such as find.

Validation

  • There is no client-side validation. auditLog accepts null and an empty string, despite the @NotNull annotation.
  • Errors come from the request method you call on the result, not from auditLog().
    • Methods that act on one audit log item, such as fetch, need the object from auditLog(String logItemUid). The AuditLog page states what each of them does without a UID.
    • An unknown UID does not throw. The API rejects the request, 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

  • Client-side only. auditLog sends no request.
  • Each call returns a new AuditLog. The new object copies the stack's headers, such as api_key, authorization and branch, when you call auditLog. A header you add to the stack later does not reach it.
  • The stack's query parameters do not reach the new object. Add them to the AuditLog object instead.

Example

Basic usage: fetch one audit log item

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.AuditLog;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class FetchAuditLogItem {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");

        AuditLog auditLog = stack.auditLog("<LOG_ITEM_UID>");
        Response<ResponseBody> response = auditLog.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());
    }
}

List the audit log of the stack

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class ListAuditLog {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");

        Response<ResponseBody> response = stack.auditLog().find().execute();
        if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
        System.out.println(response.body().string());
    }
}

branch

branch creates a Branch object for one branch, or for all the branches of the stack.

NameTypeDescription
branchUid (required)String

UID of the branch to open, for example main.

Default: Not applicable

Returns: Branch. A new branch object.

Overloads

  • branch(String branchUid)
  • branch(): This overload takes no parameters. Use it for the requests that act on all branches, such as find.

Validation

  • There is no client-side validation. branch accepts null and an empty string.
  • Errors come from the request method you call on the result, not from branch().
    • Methods that act on one branch, such as fetch, need the object from branch(String branchUid). The Branch page states what each of them does without a UID.
    • An unknown UID does not throw. The API rejects the request, 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

  • Client-side only. branch sends no request.
  • Each call returns a new Branch. The new object copies the stack's headers, such as api_key, authorization and branch, when you call branch. A header you add to the stack later does not reach it.
  • The stack's query parameters do not reach the new object. Add them to the Branch object instead.
  • branch(String branchUid) opens the branch as an object to manage. It does not scope other requests to that branch. Pass the branch to client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>", "<BRANCH>") for that.

Example

Basic usage: fetch one branch by its UID

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Branch;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class FetchBranch {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");

        Branch branch = stack.branch("<BRANCH>");
        Response<ResponseBody> response = branch.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());
    }
}

List every branch of the stack

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class ListBranches {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");

        Response<ResponseBody> response = stack.branch().find().execute();
        if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
        System.out.println(response.body().string());
    }
}

bulkOperation

bulkOperation creates a BulkOperation object, which publishes, unpublishes or deletes several entries and assets in one request.

Returns: BulkOperation. A new bulk operation object.

Validation

  • There is no client-side validation.
  • Errors come from the request method you call on the result, not from bulkOperation(). 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

  • Client-side only. bulkOperation sends no request.
  • Each call returns a new BulkOperation. The new object copies the stack's headers, such as api_key, authorization and branch, when you call bulkOperation. A header you add to the stack later does not reach it.
  • The stack's query parameters do not reach the new object. Add them to the BulkOperation object instead.

Example

Basic usage: publish one entry in bulk

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.BulkOperation;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import org.json.simple.JSONArray;
import org.json.simple.JSONObject;
import retrofit2.Response;

import java.io.IOException;

public class BulkPublishEntry {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");

        JSONObject entry = new JSONObject();
        entry.put("uid", "<ENTRY_UID>");
        entry.put("content_type", "<CONTENT_TYPE_UID>");
        entry.put("locale", "<LOCALE>");
        JSONArray entries = new JSONArray();
        entries.add(entry);
        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);

        BulkOperation bulkOperation = stack.bulkOperation();
        Response<ResponseBody> response = bulkOperation.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());
    }
}

contentType

contentType creates a ContentType object for one content type, or for all the content types of the stack.

NameTypeDescription
contentTypeUid (required)String

UID of the content type to open.

Default: Not applicable

Returns: ContentType. A new content type object.

Overloads

  • contentType(String contentTypeUid)
  • contentType(): This overload takes no parameters. Use it for the requests that act on all content types, such as find.

Validation

  • There is no client-side validation. contentType accepts null and an empty string, despite the @NotNull annotation.
  • Errors come from the request method you call on the result, not from contentType().
    • Methods that act on one content type, such as fetch, need the object from contentType(String contentTypeUid). The ContentType page states what each of them does without a UID.
    • An unknown UID does not throw. The API rejects the request, 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

  • Client-side only. contentType sends no request.
  • Each call returns a new ContentType. The new object copies the stack's headers, such as api_key, authorization and branch, when you call contentType. A header you add to the stack later does not reach it.
  • The stack's query parameters do not reach the new object. Add them to the ContentType object instead.
  • Call entry("<ENTRY_UID>") or entry() on the result to work with the entries of the content type.

Example

Basic usage: fetch one content type by its UID

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.ContentType;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class FetchContentType {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");

        ContentType contentType = stack.contentType("<CONTENT_TYPE_UID>");
        Response<ResponseBody> response = contentType.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());
    }
}

List every content type of the stack

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class ListContentTypes {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");

        Response<ResponseBody> response = stack.contentType().find().execute();
        if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
        System.out.println(response.body().string());
    }
}

create

create builds the request that creates a stack in an organization.

NameTypeDescription
organizationUid (required)String

UID of the organization that owns the new stack.

Default: Not applicable
requestBody (required)JSONObject

Stack details under a stack key, for example name, description and master_locale.

Default: Not applicable

Returns: Call<ResponseBody>. The request for the new stack, sent when you call execute().

Validation

  • There is no client-side validation. create sends requestBody unchanged.
  • An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
  • The API rejects the request when the client has no authtoken, because Create stack requires one.
  • The API allows one new stack per organization per minute, as the API reference states. A second create within the minute fails.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • One execute() sends one Create stack request (POST /stacks) with requestBody as the JSON body.
  • create sends organizationUid as the organization_uid header and no other stack header. Headers from addHeader and the stack's api_key do not reach this request. The client still adds its authtoken.
  • The master language of the stack is fixed after creation. update cannot change it.
  • The response body is the raw JSON that the API returns. Read it once with response.body().string().

Example

Basic usage: create a stack with English as the master language

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;

import java.io.IOException;

public class CreateStack {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        client.login("<EMAIL>", "<PASSWORD>");
        Stack stack = client.stack();

        JSONObject details = new JSONObject();
        details.put("name", "docs-test-stack");
        details.put("description", "Stack for the product catalog");
        details.put("master_locale", "en-us");
        JSONObject body = new JSONObject();
        body.put("stack", details);

        Response<ResponseBody> response = stack.create("<ORGANIZATION_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());
    }
}

environment

environment creates an Environment object for one environment, or for all the environments of the stack.

NameTypeDescription
environment (required)String

Name of the environment to open, not its UID.

Default: Not applicable

Returns: Environment. A new environment object.

Overloads

  • environment(String environment)
  • environment(): This overload takes no parameters. Use it for the requests that act on all environments, such as find.

Validation

  • There is no client-side validation. environment accepts null and an empty string.
  • Errors come from the request method you call on the result, not from environment().
    • Methods that act on one environment, such as fetch, need the object from environment(String environment). The Environment page states what each of them does without a name.
    • An unknown name does not throw. The API rejects the request, 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

  • Client-side only. environment sends no request.
  • Each call returns a new Environment. The new object copies the stack's headers, such as api_key, authorization and branch, when you call environment. A header you add to the stack later does not reach it.
  • The stack's query parameters do not reach the new object. Add them to the Environment object instead.
  • The Environment requests put the value of environment in the request path, so pass the environment name, for example production.

Example

Basic usage: fetch one environment by its name

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Environment;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class FetchEnvironment {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");

        Environment environment = stack.environment("<ENVIRONMENT>");
        Response<ResponseBody> response = environment.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());
    }
}

List every environment of the stack

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class ListEnvironments {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");

        Response<ResponseBody> response = stack.environment().find().execute();
        if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
        System.out.println(response.body().string());
    }
}

extensions

extensions creates an Extensions object for one extension, or for all the extensions of the stack.

NameTypeDescription
customFieldUid (required)String

UID of the extension to open.

Default: Not applicable

Returns: Extensions. A new extensions object.

Overloads

  • extensions(String customFieldUid)
  • extensions(): This overload takes no parameters. Use it for the requests that act on all extensions, such as find.

Validation

  • There is no client-side validation. extensions accepts null and an empty string.
  • Errors come from the request method you call on the result, not from extensions().
    • Methods that act on one extension, such as fetch, need the object from extensions(String customFieldUid). The Extensions page states what each of them does without a UID.
    • An unknown UID does not throw. The API rejects the request, 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

  • Client-side only. extensions sends no request.
  • Each call returns a new Extensions. The new object copies the stack's headers, such as api_key, authorization and branch, when you call extensions. A header you add to the stack later does not reach it.
  • The stack's query parameters do not reach the new object. Add them to the Extensions object instead.

Example

Basic usage: fetch one extension by its UID

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Extensions;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class FetchExtension {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");

        Extensions extension = stack.extensions("<EXTENSION_UID>");
        Response<ResponseBody> response = extension.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());
    }
}

List the extensions of the stack

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class ListExtensions {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");

        Response<ResponseBody> response = stack.extensions().find().execute();
        if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
        System.out.println(response.body().string());
    }
}

find

find builds the request that fetches the details of one stack, or lists every stack that your user account owns or shares.

Returns: Call<ResponseBody>. The request for the stack details, or for all stacks, 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().
  • The API rejects the request when the client has no authtoken, because both Get a single stack and Get all stacks require one.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • One execute() sends one GET /stacks request with the stack's headers and its query parameters.
  • The api_key header decides which request the API runs:
    • A stack from client.stack("<API_KEY>") sends the header, and the API returns that stack.
    • A stack from client.stack() sends no API key, and the API returns every stack owned by or shared with your user account.
  • Add query parameters with addParam before you call find. The API accepts include_collaborators, include_stack_variables, include_discrete_variables and include_count. When you send none, the API applies its own defaults.
  • For an organization with single sign-on (SSO), the API requires the organization_uid header. Add it with addHeader.
  • The response body is the raw JSON that the API returns. Read it once with response.body().string().

Example

Basic usage: fetch one stack

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class FetchStack {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        client.login("<EMAIL>", "<PASSWORD>");
        Stack stack = client.stack("<API_KEY>");

        Response<ResponseBody> response = stack.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());
    }
}

All options: list every stack of an SSO organization with collaborators and a count

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class ListAllStacks {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        client.login("<EMAIL>", "<PASSWORD>");
        Stack stack = client.stack()
                .addHeader("organization_uid", "<ORGANIZATION_UID>")
                .addParam("include_collaborators", true)
                .addParam("include_stack_variables", true)
                .addParam("include_discrete_variables", true)
                .addParam("include_count", true);

        Response<ResponseBody> response = stack.find().execute();
        if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
        System.out.println(response.body().string());
    }
}

globalField

globalField creates a GlobalField object for one global field, or for all the global fields of the stack.

NameTypeDescription
globalFiledUid (required)String

UID of the global field to open. The SDK spells the name globalFiledUid.

Default: Not applicable

Returns: GlobalField. A new global field object.

Overloads

  • globalField(String globalFiledUid)
  • globalField(): This overload takes no parameters. Use it for the requests that act on all global fields, such as find.

Validation

  • There is no client-side validation. globalField accepts null and an empty string, despite the @NotNull annotation.
  • Errors come from the request method you call on the result, not from globalField().
    • Methods that act on one global field, such as fetch, need the object from globalField(String globalFiledUid). The GlobalField page states what each of them does without a UID.
    • An unknown UID does not throw. The API rejects the request, 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

  • Client-side only. globalField sends no request.
  • Each call returns a new GlobalField. The new object copies the stack's headers, such as api_key, authorization and branch, when you call globalField. A header you add to the stack later does not reach it.
  • The stack's query parameters do not reach the new object. Add them to the GlobalField object instead.

Example

Basic usage: fetch one global field by its UID

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.GlobalField;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class FetchGlobalField {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");

        GlobalField globalField = stack.globalField("<GLOBAL_FIELD_UID>");
        Response<ResponseBody> response = globalField.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());
    }
}

List every global field of the stack

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class ListGlobalFields {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");

        Response<ResponseBody> response = stack.globalField().find().execute();
        if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
        System.out.println(response.body().string());
    }
}

label

label creates a Label object for one label, or for all the labels of the stack.

NameTypeDescription
labelUid (required)String

UID of the label to open.

Default: Not applicable

Returns: Label. A new label object.

Overloads

  • label(String labelUid)
  • label(): This overload takes no parameters. Use it for the requests that act on all labels, such as find.

Validation

  • There is no client-side validation. label accepts null and an empty string.
  • Errors come from the request method you call on the result, not from label().
    • Methods that act on one label, such as fetch, need the object from label(String labelUid). The Label page states what each of them does without a UID.
    • An unknown UID does not throw. The API rejects the request, 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

  • Client-side only. label sends no request.
  • Each call returns a new Label. The new object copies the stack's headers, such as api_key, authorization and branch, when you call label. A header you add to the stack later does not reach it.
  • The stack's query parameters do not reach the new object. Add them to the Label object instead.

Example

Basic usage: fetch one label by its UID

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Label;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class FetchLabel {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");

        Label label = stack.label("<LABEL_UID>");
        Response<ResponseBody> response = label.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());
    }
}

List every label of the stack

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class ListLabels {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");

        Response<ResponseBody> response = stack.label().find().execute();
        if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
        System.out.println(response.body().string());
    }
}

locale

locale creates a Locale object for one language, or for all the languages of the stack.

NameTypeDescription
code (required)String

Code of the language to open, for example fr-fr.

Default: Not applicable

Returns: Locale. A new locale object.

Overloads

  • locale(String code)
  • locale(): This overload takes no parameters. Use it for the requests that act on all languages, such as find.

Validation

  • There is no client-side validation. locale accepts null and an empty string.
  • Errors come from the request method you call on the result, not from locale().
    • Methods that act on one language, such as fetch, need the object from locale(String code). The Locale page states what each of them does without a code.
    • An unknown code does not throw. The API rejects the request, 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

  • Client-side only. locale sends no request.
  • Each call returns a new Locale. The new object copies the stack's headers, such as api_key, authorization and branch, when you call locale. A header you add to the stack later does not reach it.
  • The stack's query parameters do not reach the new object. Add them to the Locale object instead.

Example

Basic usage: fetch one language by its code

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Locale;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class FetchLanguage {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");

        Locale locale = stack.locale("<LOCALE>");
        Response<ResponseBody> response = locale.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());
    }
}

List every language of the stack

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class ListLanguages {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");

        Response<ResponseBody> response = stack.locale().find().execute();
        if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
        System.out.println(response.body().string());
    }
}

publishQueue

publishQueue creates a PublishQueue object for one publish queue activity, or for all the publish queue activities of the stack.

NameTypeDescription
publishQueueUid (required)String

UID of the publish queue activity to open.

Default: Not applicable

Returns: PublishQueue. A new publish queue object.

Overloads

  • publishQueue(String publishQueueUid)
  • publishQueue(): This overload takes no parameters. Use it for the requests that act on all publish queue activities, such as find.

Validation

  • There is no client-side validation. publishQueue accepts null and an empty string, despite the @NotNull annotation.
  • Errors come from the request method you call on the result, not from publishQueue().
    • Methods that act on one publish queue activity, such as fetchActivity, need the object from publishQueue(String publishQueueUid). The PublishQueue page states what each of them does without a UID.
    • An unknown UID does not throw. The API rejects the request, 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

  • Client-side only. publishQueue sends no request.
  • Each call returns a new PublishQueue. The new object copies the stack's headers, such as api_key, authorization and branch, when you call publishQueue. A header you add to the stack later does not reach it.
  • The stack's query parameters do not reach the new object. Add them to the PublishQueue object instead.

Example

Basic usage: fetch one publish queue activity

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.PublishQueue;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class FetchPublishQueueActivity {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");

        PublishQueue publishQueue = stack.publishQueue("<PUBLISH_QUEUE_UID>");
        Response<ResponseBody> response = publishQueue.fetchActivity().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());
    }
}

List the publish queue of the stack

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class ListPublishQueue {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");

        Response<ResponseBody> response = stack.publishQueue().find().execute();
        if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
        System.out.println(response.body().string());
    }
}

releases

releases creates a Release object for one release, or for all the releases of the stack.

NameTypeDescription
releaseUid (required)String

UID of the release to open.

Default: Not applicable

Returns: Release. A new release object.

Overloads

  • releases(String releaseUid)
  • releases(): This overload takes no parameters. Use it for the requests that act on all releases, such as find.

Validation

  • There is no client-side validation. releases accepts null and an empty string.
  • Errors come from the request method you call on the result, not from releases().
    • Methods that act on one release, such as fetch, need the object from releases(String releaseUid). The Release page states what each of them does without a UID.
    • An unknown UID does not throw. The API rejects the request, 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

  • Client-side only. releases sends no request.
  • Each call returns a new Release. The new object copies the stack's headers, such as api_key, authorization and branch, when you call releases. A header you add to the stack later does not reach it.
  • The stack's query parameters do not reach the new object. Add them to the Release object instead.

Example

Basic usage: fetch one release by its UID

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Release;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class FetchRelease {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");

        Release release = stack.releases("<RELEASE_UID>");
        Response<ResponseBody> response = release.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());
    }
}

List every release of the stack

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class ListReleases {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");

        Response<ResponseBody> response = stack.releases().find().execute();
        if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
        System.out.println(response.body().string());
    }
}

removeParam

removeParam removes one query parameter from the stack, so later find and acceptOwnership requests no longer send it.

NameTypeDescription
key (required)String

Name of the query parameter to remove.

Default: Not applicable

Returns: Stack. The same stack, for chaining.

Validation

  • There is no client-side validation. A key that the stack 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

  • Client-side only. removeParam deletes the entry from the stack's query parameter map and sends no request.

Example

Basic usage: drop the count from a repeated stack list

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class ListStacksWithoutCount {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        client.login("<EMAIL>", "<PASSWORD>");
        Stack stack = client.stack().addParam("include_count", true);

        Response<ResponseBody> first = stack.find().execute();
        if (!first.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + first.code() + " " + first.errorBody().string());
            return;
        }
        System.out.println(first.body().string());

        stack.removeParam("include_count");
        Response<ResponseBody> second = stack.find().execute();
        if (!second.isSuccessful()) { System.out.println(second.errorBody().string()); return; }
        System.out.println(second.body().string());
    }
}

resetSetting

resetSetting builds a request that sends stack settings through the Add stack settings request, the same request as updateSetting.

NameTypeDescription
requestBody (required)JSONObject

Settings under a stack_settings key.

Default: Not applicable

Returns: Call<ResponseBody>. The request for the updated stack settings, sent when you call execute().

Validation

  • There is no client-side validation. resetSetting sends requestBody unchanged.
  • An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
  • The API rejects the request when the client has no authtoken, because Add stack settings requires one.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • One execute() sends one Add stack settings request (POST /stacks/settings) with the stack's headers and requestBody as the JSON body. resetSetting and updateSetting send the same request.
  • resetSetting sends no query parameters.

Limitations

  • Does not call Reset stack settings (POST /stacks/settings/reset). The SDK has no method for that request.

Example

Basic usage: send settings with empty variable groups

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;

import java.io.IOException;

public class SendEmptySettings {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        client.login("<EMAIL>", "<PASSWORD>");
        Stack stack = client.stack("<API_KEY>");

        JSONObject settings = new JSONObject();
        settings.put("discrete_variables", new JSONObject());
        settings.put("stack_variables", new JSONObject());
        JSONObject body = new JSONObject();
        body.put("stack_settings", settings);

        // resetSetting sends POST /stacks/settings, so the stack keeps its current settings
        Response<ResponseBody> response = stack.resetSetting(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());
    }
}

roles

roles creates a Roles object for one role or for all roles. With a request body, it builds the request that replaces the roles of existing users.

NameTypeDescription
roleUid (required)String

UID of the role to open.

Default: Not applicable
body (required)JSONObject

Maps each user UID to the role UIDs to assign, under a users key.

Default: Not applicable

Returns: Roles or Call<ResponseBody>. A new roles object, or the request to update user roles, sent when you call execute().

Overloads

  • roles(String roleUid)
  • roles(): This overload takes no parameters. Use it for the requests that act on all roles, such as find.
  • roles(JSONObject body)

Validation

  • There is no client-side validation. roles(String roleUid) accepts null and an empty string. roles(JSONObject body) sends the body unchanged.
  • Errors come from execute(), either on the request that roles(JSONObject body) returns, or on a request method of the Roles object.
    • An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
    • The API rejects roles(JSONObject body) when the client has no authtoken, because Update User Role requires one.

Additional Resource Refer to Content Management API Errors for the full error code list.

Warning roles(JSONObject body) replaces the roles of each user in the body. The user loses every role that the body does not list. Send the request again with the old roles to restore them.

Behavior

  • roles() and roles(String roleUid) are client-side only. Each returns a new Roles object that copies the stack's headers when you call it. A header you add to the stack later does not reach it.
  • roles(JSONObject body) builds one Update User Role request (POST /stacks/users/roles) with the stack's headers and no query parameters. execute() sends it.
  • The update replaces the existing roles of each user in the body. For example, a user with the Developer role who receives only the Content Manager role loses the Developer rights, as the API reference states.

Example

Basic usage: fetch one role by its UID

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Roles;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class FetchRole {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");

        Roles role = stack.roles("<ROLE_UID>");
        Response<ResponseBody> response = role.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());
    }
}

List every role of the stack

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class ListRoles {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");

        Response<ResponseBody> response = stack.roles().find().execute();
        if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
        System.out.println(response.body().string());
    }
}

Replace the roles of a user

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import org.json.simple.JSONArray;
import org.json.simple.JSONObject;
import retrofit2.Response;

import java.io.IOException;

public class UpdateUserRoles {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        client.login("<EMAIL>", "<PASSWORD>");
        Stack stack = client.stack("<API_KEY>");

        JSONArray roleUids = new JSONArray();
        roleUids.add("<ROLE_UID>");
        JSONObject users = new JSONObject();
        users.put("<USER_UID>", roleUids);
        JSONObject body = new JSONObject();
        body.put("users", users);

        Response<ResponseBody> response = stack.roles(body).execute();
        if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
        System.out.println(response.body().string());
    }
}

setting

setting builds the request that retrieves the configuration settings of the stack.

Returns: Call<ResponseBody>. The request for the stack settings, 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().
  • The API rejects the request when the client has no authtoken, because Get stack settings requires one. A stack that you open with only a management token fails here.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • One execute() sends one Get stack settings request (GET /stacks/settings) with the stack's headers.
  • setting sends no query parameters. Values from addParam do not reach this request.
  • The response body is the raw JSON that the API returns. Read it once with response.body().string().
  • When Disable Fallback Publishing is on for your organization, the API adds the disable_fallback_publish key to the response, as the API reference states.

Example

Basic usage: print the stack settings

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class FetchStackSettings {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        client.login("<EMAIL>", "<PASSWORD>");
        Stack stack = client.stack("<API_KEY>");

        Response<ResponseBody> response = stack.setting().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());
    }
}

share

share builds the request that shares the stack with users and assigns each of them roles.

NameTypeDescription
requestBody (required)JSONObject

User emails under emails, and the role UIDs per email under roles.

Default: Not applicable

Returns: Call<ResponseBody>. The request for sharing the stack, sent when you call execute().

Validation

  • There is no client-side validation. share sends requestBody unchanged.
  • An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
  • The API rejects the request when the client has no authtoken, because Share a stack requires one.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • One execute() sends one Share a stack request (POST /stacks/share) with the stack's headers and requestBody as the JSON body.
  • share sends no query parameters.
  • Use the unshare method to remove a user from the stack.

Example

Basic usage: share the stack with one user

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import org.json.simple.JSONArray;
import org.json.simple.JSONObject;
import retrofit2.Response;

import java.io.IOException;

public class ShareStack {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        client.login("<EMAIL>", "<PASSWORD>");
        Stack stack = client.stack("<API_KEY>");

        JSONArray emails = new JSONArray();
        emails.add("<COLLABORATOR_EMAIL>");
        JSONArray roleUids = new JSONArray();
        roleUids.add("<ROLE_UID>");
        JSONObject roles = new JSONObject();
        roles.put("<COLLABORATOR_EMAIL>", roleUids);
        JSONObject body = new JSONObject();
        body.put("emails", emails);
        body.put("roles", roles);

        Response<ResponseBody> response = stack.share(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());
    }
}

taxonomy

taxonomy creates a Taxonomy object for one taxonomy, or for all the taxonomies of the stack.

NameTypeDescription
taxonomyUid (required)String

UID of the taxonomy to open.

Default: Not applicable

Returns: Taxonomy. A new taxonomy object.

Overloads

  • taxonomy(String taxonomyUid)
  • taxonomy(): This overload takes no parameters. Use it for the requests that act on all taxonomies, such as find.

Validation

  • There is no client-side validation. taxonomy accepts null and an empty string, despite the @NotNull annotation.
  • Errors come from the request method you call on the result, not from taxonomy().
    • Methods that act on one taxonomy, such as terms, need the object from taxonomy(String taxonomyUid). The Taxonomy page states what each of them does without a UID.
    • An unknown UID does not throw. The API rejects the request, 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

  • Client-side only. taxonomy sends no request.
  • Each call returns a new Taxonomy. The new object copies the stack's headers, such as api_key, authorization and branch, when you call taxonomy. A header you add to the stack later does not reach it.
  • The stack's query parameters do not reach the new object. Add them to the Taxonomy object instead.
  • The Taxonomy methods fetch, update and delete take the taxonomy UID as their own argument. The UID from taxonomy(String taxonomyUid) serves terms, localize and unlocalize.

Example

Basic usage: list the terms of one taxonomy

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Taxonomy;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class ListTaxonomyTerms {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");

        Taxonomy taxonomy = stack.taxonomy("<TAXONOMY_UID>");
        Response<ResponseBody> response = taxonomy.terms().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());
    }
}

List every taxonomy of the stack

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class ListTaxonomies {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");

        Response<ResponseBody> response = stack.taxonomy().find().execute();
        if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
        System.out.println(response.body().string());
    }
}

tokens

tokens creates a Tokens object, which opens the delivery tokens and management tokens of the stack.

Returns: Tokens. A new tokens object.

Validation

  • There is no client-side validation.
  • Errors come from the request method you call on a DeliveryToken or ManagementToken that the result creates, not from tokens().
    • An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
    • The Tokens requests require an authtoken, as the Get all delivery tokens request states. Open the stack from a logged-in client.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Client-side only. tokens sends no request.
  • Unlike the other factory methods, the Tokens object keeps the stack's own header map instead of a copy. A header you add to the stack later reaches every DeliveryToken or ManagementToken that the Tokens object creates after that.
  • Call deliveryTokens() or managementToken() on the result to work with one token type.

Example

Basic usage: list the delivery tokens of the stack

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Stack;
import com.contentstack.cms.stack.Tokens;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class ListDeliveryTokens {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        client.login("<EMAIL>", "<PASSWORD>");
        Stack stack = client.stack("<API_KEY>");

        Tokens tokens = stack.tokens();
        Response<ResponseBody> response = tokens.deliveryTokens().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());
    }
}

Fetch one management token

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class FetchManagementToken {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        client.login("<EMAIL>", "<PASSWORD>");
        Stack stack = client.stack("<API_KEY>");

        Response<ResponseBody> response = stack.tokens().managementToken("<TOKEN_UID>").fetch().execute();
        if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
        System.out.println(response.body().string());
    }
}

transferOwnership

transferOwnership builds the request that emails a user an invitation to take ownership of the stack.

NameTypeDescription
body (required)JSONObject

Email of the new owner, under a transfer_to key.

Default: Not applicable

Returns: Call<ResponseBody>. The request for the ownership transfer invitation, sent when you call execute().

Validation

  • There is no client-side validation. transferOwnership sends body unchanged.
  • An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
  • The API rejects the request when the client has no authtoken, because Transfer stack ownership to other users requires one.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • One execute() sends one Transfer stack ownership to other users request (POST /stacks/transfer_ownership) with the stack's headers and body as the JSON body.
  • transferOwnership sends no query parameters.
  • The transfer completes only when the new owner accepts. The invitation email holds a link with the ownership token, which the acceptOwnership method takes.

Example

Basic usage: invite a new owner

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;

import java.io.IOException;

public class TransferStackOwnership {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        client.login("<EMAIL>", "<PASSWORD>");
        Stack stack = client.stack("<API_KEY>");

        JSONObject body = new JSONObject();
        body.put("transfer_to", "<NEW_OWNER_EMAIL>");

        Response<ResponseBody> response = stack.transferOwnership(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());
    }
}

unshare

unshare builds the request that removes a user from the collaborators of the stack.

NameTypeDescription
requestBody (required)JSONObject

Email of the user to remove, under an email key.

Default: Not applicable

Returns: Call<ResponseBody>. The request for removing a collaborator, sent when you call execute().

Validation

  • There is no client-side validation. unshare sends requestBody unchanged.
  • An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
  • The API rejects the request when the client has no authtoken, because Unshare a stack requires one.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • One execute() sends one Unshare a stack request (POST /stacks/unshare) with the stack's headers and requestBody as the JSON body.
  • unshare sends no query parameters.

Example

Basic usage: remove a user from the stack

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;

import java.io.IOException;

public class UnshareStack {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        client.login("<EMAIL>", "<PASSWORD>");
        Stack stack = client.stack("<API_KEY>");

        JSONObject body = new JSONObject();
        body.put("email", "<COLLABORATOR_EMAIL>");

        Response<ResponseBody> response = stack.unshare(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 builds the request that updates the name and description of the stack.

NameTypeDescription
requestBody (required)JSONObject

New name and description under a stack key.

Default: Not applicable

Returns: Call<ResponseBody>. The request for the updated stack, sent when you call execute().

Validation

  • There is no client-side validation. update sends requestBody unchanged.
  • An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
  • The API rejects the request when the client has no authtoken or the stack has no api_key header, because Update stack requires both.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • One execute() sends one Update stack request (PUT /stacks) with the stack's headers and requestBody as the JSON body.
  • update sends no query parameters.
  • The API does not change the master language of a stack. Choose it in create.
  • The response body is the raw JSON that the API returns. Read it once with response.body().string().

Example

Basic usage: rename the stack

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;

import java.io.IOException;

public class RenameStack {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        client.login("<EMAIL>", "<PASSWORD>");
        Stack stack = client.stack("<API_KEY>");

        JSONObject details = new JSONObject();
        details.put("name", "Product Catalog");
        details.put("description", "Content for the product catalog website");
        JSONObject body = new JSONObject();
        body.put("stack", details);

        Response<ResponseBody> response = stack.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());
    }
}

updateSetting

updateSetting builds the request that adds settings to the stack or changes existing ones.

NameTypeDescription
requestBody (required)JSONObject

Settings under a stack_settings key, for example in stack_variables.

Default: Not applicable

Returns: Call<ResponseBody>. The request for the updated stack settings, sent when you call execute().

Validation

  • There is no client-side validation. updateSetting sends requestBody unchanged.
  • An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
  • The API rejects the request when the client has no authtoken, because Add stack settings requires one.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • One execute() sends one Add stack settings request (POST /stacks/settings) with the stack's headers and requestBody as the JSON body.
  • updateSetting sends no query parameters.
  • The API reference lists the settings that stack_variables accepts, for example the two below:
    • enforce_unique_urls set to true stops two entries from sharing a URL across the stack.
    • sys_rte_allowed_tags lists the HTML tags that the Rich Text Editor keeps, from figure, style and script.
  • The response body is the raw JSON that the API returns. Read it once with response.body().string().

Example

Basic usage: enforce unique entry URLs

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;

import java.io.IOException;

public class EnforceUniqueUrls {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        client.login("<EMAIL>", "<PASSWORD>");
        Stack stack = client.stack("<API_KEY>");

        JSONObject stackVariables = new JSONObject();
        stackVariables.put("enforce_unique_urls", true);
        stackVariables.put("sys_rte_allowed_tags", "figure, style");
        JSONObject settings = new JSONObject();
        settings.put("stack_variables", stackVariables);
        JSONObject body = new JSONObject();
        body.put("stack_settings", settings);

        Response<ResponseBody> response = stack.updateSetting(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());
    }
}

variantGroup

variantGroup creates a VariantGroup object for one variant group, or for all the variant groups of the stack.

NameTypeDescription
variantGroupUid (required)String

UID of the variant group to open.

Default: Not applicable

Returns: VariantGroup. A new variant group object.

Overloads

  • variantGroup(String variantGroupUid)
  • variantGroup(): This overload takes no parameters. Use it for the requests that act on all variant groups, such as find.

Validation

  • There is no client-side validation. variantGroup accepts null and an empty string, despite the @NotNull annotation.
  • Errors come from the request method you call on the result, not from variantGroup().
    • Methods that act on one variant group, such as linkContentTypes, need the object from variantGroup(String variantGroupUid). The VariantGroup page states what each of them does without a UID.
    • An unknown UID does not throw. The API rejects the request, 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

  • Client-side only. variantGroup sends no request.
  • Each call returns a new VariantGroup. The new object copies the stack's headers, such as api_key, authorization and branch, when you call variantGroup. A header you add to the stack later does not reach it.
  • The stack's query parameters do not reach the new object. Add them to the VariantGroup object instead.
  • linkContentTypes and unlinkContentTypes act on one variant group, so call them on the object from variantGroup(String variantGroupUid).

Example

Basic usage: link a content type to one variant group

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.VariantGroup;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class LinkContentTypeToVariantGroup {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");

        VariantGroup variantGroup = stack.variantGroup("<VARIANT_GROUP_UID>");
        Response<ResponseBody> response = variantGroup.linkContentTypes("<CONTENT_TYPE_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());
    }
}

List every variant group of the stack

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class ListVariantGroups {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");

        Response<ResponseBody> response = stack.variantGroup().find().execute();
        if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
        System.out.println(response.body().string());
    }
}

webhook

webhook creates a Webhook object for one webhook, or for all the webhooks of the stack.

NameTypeDescription
webhookUid (required)String

UID of the webhook to open.

Default: Not applicable

Returns: Webhook. A new webhook object.

Overloads

  • webhook(String webhookUid)
  • webhook(): This overload takes no parameters. Use it for the requests that act on all webhooks, such as find.

Validation

  • There is no client-side validation. webhook accepts null and an empty string.
  • Errors come from the request method you call on the result, not from webhook().
    • Methods that act on one webhook, such as fetch, need the object from webhook(String webhookUid). The Webhook page states what each of them does without a UID.
    • An unknown UID does not throw. The API rejects the request, 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

  • Client-side only. webhook sends no request.
  • Each call returns a new Webhook. The new object copies the stack's headers, such as api_key, authorization and branch, when you call webhook. A header you add to the stack later does not reach it.
  • The stack's query parameters do not reach the new object. Add them to the Webhook object instead.

Example

Basic usage: fetch one webhook by its UID

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Webhook;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class FetchWebhook {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");

        Webhook webhook = stack.webhook("<WEBHOOK_UID>");
        Response<ResponseBody> response = webhook.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());
    }
}

List every webhook of the stack

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class ListWebhooks {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");

        Response<ResponseBody> response = stack.webhook().find().execute();
        if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
        System.out.println(response.body().string());
    }
}

workflow

workflow creates a Workflow object for one workflow, or for all the workflows of the stack.

NameTypeDescription
workflowUid (required)String

UID of the workflow to open.

Default: Not applicable

Returns: Workflow. A new workflow object.

Overloads

  • workflow(String workflowUid)
  • workflow(): This overload takes no parameters. Use it for the requests that act on all workflows, such as find.

Validation

  • There is no client-side validation. workflow accepts null and an empty string, despite the @NotNull annotation.
  • Errors come from the request method you call on the result, not from workflow().
    • Methods that act on one workflow, such as fetch, need the object from workflow(String workflowUid). The Workflow page states what each of them does without a UID.
    • An unknown UID does not throw. The API rejects the request, 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

  • Client-side only. workflow sends no request.
  • Each call returns a new Workflow. The new object copies the stack's headers, such as api_key, authorization and branch, when you call workflow. A header you add to the stack later does not reach it.
  • The stack's query parameters do not reach the new object. Add them to the Workflow object instead.

Example

Basic usage: fetch one workflow by its UID

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Workflow;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class FetchWorkflow {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");

        Workflow workflow = stack.workflow("<WORKFLOW_UID>");
        Response<ResponseBody> response = workflow.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());
    }
}

List every workflow of the stack

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class ListWorkflows {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");

        Response<ResponseBody> response = stack.workflow().find().execute();
        if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
        System.out.println(response.body().string());
    }
}