Organization
Organization
Organization builds requests against one Contentstack organization, the top level that holds stacks and users. Use this class to
- list your organizations, or read the details, roles and stacks of one
- invite users, remove them, and manage pending invitations
- transfer the ownership of the organization
- read the audit log of the organization
Get an object with the organization method of Contentstack, after login or an Open Authorization (OAuth) sign-in.
addHeader
addHeader adds one header that every request of this organization object sends.
| Name | Type | Description |
|---|---|---|
| key (required) | String | Name of the header. |
| value (required) | String | Value of the header. |
Returns: Organization. The same organization, 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.
- A null key or value does not throw here. execute() on the next request throws IllegalArgumentException.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Every request method of this object sends the header, including inviteUser and logsDetails.
- The header stays on the object for later requests. No public method removes it.
- A second call with the same key replaces the value.
Example
Basic usage: send a header with a request
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.organization.Organization;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class AddOrganizationHeader {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
client.login("<EMAIL>", "<PASSWORD>");
Organization organization = client.organization("<ORGANIZATION_UID>");
Response<ResponseBody> response = organization.addHeader("x-request-id", "docs-test-1").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());
}
}addHeaders
addHeaders adds every entry of a map as a header that every request of this organization object sends.
| Name | Type | Description |
|---|---|---|
| headers (required) | HashMap<String, String> | Header names and values to add. |
Returns: Organization. The same organization, 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.
- A null key or value does not throw here. execute() on the next request throws IllegalArgumentException.
- A null map throws NullPointerException at the call.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- addHeaders copies the entries into the headers of this object. A later change to your map does not change them.
- An entry replaces an earlier header with the same key.
- Every request method of this object sends the headers.
Example
Basic usage: send two headers
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.organization.Organization;
import java.util.HashMap;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class AddOrganizationHeaders {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
client.login("<EMAIL>", "<PASSWORD>");
Organization organization = client.organization("<ORGANIZATION_UID>");
HashMap<String, String> headers = new HashMap<String, String>();
headers.put("x-request-id", "docs-test-2");
headers.put("x-team", "content-ops");
Response<ResponseBody> response = organization.addHeaders(headers).stacks().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 requests of this organization object that accept query parameters.
| Name | Type | Description |
|---|---|---|
| key (required) | String | Name of the query parameter. |
| value (required) | Object | Value of the query parameter, sent as text. |
Returns: Organization. The same organization, 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.
- A null key or value does not throw here. execute() on the next request that sends the query parameters throws IllegalArgumentException.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- find, fetch, roles, stacks and allInvitations send the query parameters. The other request methods do not.
- The SDK sends the value as text, so true and 10 become true and 10 in the URL.
- The parameter stays on the object and goes with every later request that sends query parameters. Use a new object from client.organization(...) for a request without it.
- A second call with the same key replaces the value.
Example
Basic usage: count the stacks
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.organization.Organization;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class CountOrganizationStacks {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
client.login("<EMAIL>", "<PASSWORD>");
Organization organization = client.organization("<ORGANIZATION_UID>");
Response<ResponseBody> response = organization.addParam("include_count", true).stacks().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());
}
}addParams
addParams adds every entry of a map as a query parameter of the requests of this organization object that accept query parameters.
| Name | Type | Description |
|---|---|---|
| params (required) | HashMap<String, Object> | Query parameter names and values to add. |
Returns: Organization. The same organization, 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.
- A null key or value does not throw here. execute() on the next request that sends the query parameters throws IllegalArgumentException.
- A null map throws NullPointerException at the call.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- find, fetch, roles, stacks and allInvitations send the query parameters. The other request methods do not.
- addParams copies the entries. A later change to your map does not change them.
- An entry replaces an earlier parameter with the same key.
Example
Basic usage: page through the roles
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.organization.Organization;
import java.util.HashMap;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class PageOrganizationRoles {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
client.login("<EMAIL>", "<PASSWORD>");
Organization organization = client.organization("<ORGANIZATION_UID>");
HashMap<String, Object> params = new HashMap<String, Object>();
params.put("limit", 10);
params.put("skip", 10);
params.put("include_count", true);
Response<ResponseBody> response = organization.addParams(params).roles().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());
}
}allInvitations
allInvitations builds the request that lists the invitations that users of this organization sent.
| Name | Type | Description |
|---|---|---|
| limit | int | Maximum number of items to return. |
| skip | int | Number of items to skip. |
| asc | String | Field UID to sort by in ascending order. |
| desc | String | Field UID to sort by in descending order. |
| include_count | boolean | true adds the total count to the response. |
| include_roles | boolean | true adds the roles of each invited user. |
| include_invited_by | boolean | true adds the user who sent each invitation. |
| include_user_details | boolean | true adds whether each user has two-factor authentication on. |
| typeahead | String | Text that filters invitations by email address. |
Returns: Call<ResponseBody>. The request for the organization's invitations, sent when you call execute().
Validation
- Throws NullPointerException if the organization has no UID, as after client.organization() without an argument, because the request path needs the UID.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One execute() sends one Get all Organization invitations request (GET /organizations/{organization_uid}/share), with the headers and query parameters of this object.
- The response body is the raw JSON of the API. Each invitation carries a UID that resendInvitation takes.
Example
Basic usage: list the invitations
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.organization.Organization;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class ListInvitations {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
client.login("<EMAIL>", "<PASSWORD>");
Organization organization = client.organization("<ORGANIZATION_UID>");
Response<ResponseBody> response = organization.allInvitations().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}All parameters: include roles, inviters and user details
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.organization.Organization;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class ListInvitationDetails {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
client.login("<EMAIL>", "<PASSWORD>");
Organization organization = client.organization("<ORGANIZATION_UID>");
Response<ResponseBody> response = organization
.addParam("limit", 50)
.addParam("skip", 0)
.addParam("desc", "created_at")
.addParam("include_count", true)
.addParam("include_roles", true)
.addParam("include_invited_by", true)
.addParam("include_user_details", true)
.addParam("typeahead", "example.com")
.allInvitations()
.execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}fetch
fetch builds the request that reads the details of this organization.
| Name | Type | Description |
|---|---|---|
| include_plan | boolean | true adds the plan details to the response. |
Returns: Call<ResponseBody>. The request for the organization, sent when you call execute().
Validation
- Throws NullPointerException if the organization has no UID, as after client.organization() without an argument, because the request path needs the UID.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One execute() sends one Get a single Organization request (GET /organizations/{organization_uid}), with the headers and query parameters of this object.
- The response body is the raw JSON of the API, with the details under an organization key.
Example
Basic usage: read one organization
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.organization.Organization;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class FetchOrganization {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
client.login("<EMAIL>", "<PASSWORD>");
Organization organization = client.organization("<ORGANIZATION_UID>");
Response<ResponseBody> response = organization.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());
}
}All parameters: include the plan details
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.organization.Organization;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class FetchOrganizationPlan {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
client.login("<EMAIL>", "<PASSWORD>");
Organization organization = client.organization("<ORGANIZATION_UID>");
Response<ResponseBody> response = organization.addParam("include_plan", true).fetch().execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}find
find builds the request that lists every organization the signed-in user belongs to, in the order of their creation.
| Name | Type | Description |
|---|---|---|
| limit | int | Maximum number of items to return. |
| skip | int | Number of items to skip. |
| asc | String | Field UID to sort by in ascending order. |
| desc | String | Field UID to sort by in descending order. |
| include_count | boolean | true adds the total count to the response. |
| typeahead | String | Text that filters organizations by name. |
Returns: Call<ResponseBody>. The request for all organizations of the user, sent when you call execute().
Validation
- There is no client-side validation. find needs no organization UID, so it works on any Organization object.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One execute() sends one Get all Organizations request (GET /organizations), with the headers and query parameters of this object.
- The response body is the raw JSON of the API, with the organizations in an organizations array.
- find does not page through the results. Set limit and skip with addParam, and send one request per page.
Example
Basic usage: list your organizations
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.organization.Organization;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class ListOrganizations {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
client.login("<EMAIL>", "<PASSWORD>");
Organization organization = client.organization();
Response<ResponseBody> response = organization.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 parameters: page and search the list
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.organization.Organization;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class SearchOrganizations {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
client.login("<EMAIL>", "<PASSWORD>");
Organization organization = client.organization();
Response<ResponseBody> response = organization
.addParam("limit", 10)
.addParam("skip", 0)
.addParam("asc", "created_at")
.addParam("include_count", true)
.addParam("typeahead", "marketing")
.find()
.execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}inviteUser
inviteUser builds the request that sends invitations to join this organization, with a product role and optional stack roles for each user.
| Name | Type | Description |
|---|---|---|
| body (required) | JSONObject | Request body with the invitations under a share key. |
| body.share.users (required) | Object | Maps each email address to a list of product role UIDs. |
| body.share.stacks | Object | Maps each email address to stack API keys and their stack role UIDs. |
| body.share.message | String | Message in the invitation email. |
Returns: Call<ResponseBody>. The request that invites the users, sent when you call execute().
Validation
- Throws NullPointerException if the organization has no UID, as after client.organization() without an argument, because the request path needs the UID.
- inviteUser does not check body. A null body makes execute() throw IllegalArgumentException.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One execute() sends one Add users to Organization request (POST /organizations/{organization_uid}/share) with body as the JSON body.
- inviteUser sends the headers of this object but not its query parameters.
- Only the owner or an admin of the organization can invite users, as the API reference states.
- Get the product role UIDs from roles.
Example
Basic usage: invite an author with a stack role
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.organization.Organization;
import java.util.Arrays;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class InviteAuthor {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
client.login("<EMAIL>", "<PASSWORD>");
Organization organization = client.organization("<ORGANIZATION_UID>");
JSONObject users = new JSONObject();
users.put("[email protected]", Arrays.asList("<ROLE_UID>"));
JSONObject stackRoles = new JSONObject();
stackRoles.put("<API_KEY>", Arrays.asList("<ROLE_UID>"));
JSONObject stacks = new JSONObject();
stacks.put("[email protected]", stackRoles);
JSONObject share = new JSONObject();
share.put("users", users);
share.put("stacks", stacks);
share.put("message", "Welcome to the content team");
JSONObject body = new JSONObject();
body.put("share", share);
Response<ResponseBody> response = organization.inviteUser(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());
}
}logItem
logItem builds the request that reads one item of the audit log of this organization.
| Name | Type | Description |
|---|---|---|
| logUid (required) | String | UID of the audit log item. |
Returns: Call<ResponseBody>. The request for the audit log item, sent when you call execute().
Validation
- Throws NullPointerException if the organization has no UID, as after client.organization() without an argument, because the request path needs the UID.
- logItem does not check logUid. A null value makes execute() throw IllegalArgumentException.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One execute() sends one Get organization log item request (GET /organizations/{organization_uid}/logs/{log_uid}).
- logItem sends the headers of this object but not its query parameters.
- Get the log item UID from logsDetails.
Example
Basic usage: read one log item
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.organization.Organization;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class ReadOrganizationLogItem {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
client.login("<EMAIL>", "<PASSWORD>");
Organization organization = client.organization("<ORGANIZATION_UID>");
String logUid = args[0]; // a log item UID from logsDetails
Response<ResponseBody> response = organization.logItem(logUid).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());
}
}logsDetails
logsDetails builds the request that reads the audit log of this organization.
Returns: Call<ResponseBody>. The request for the organization's audit log, sent when you call execute().
Validation
- logsDetails does not check the organization UID itself. On an organization without a UID, execute() throws IllegalArgumentException, because the request path needs the UID.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One execute() sends one Get organization log details request (GET /organizations/{organization_uid}/logs).
- logsDetails sends the headers of this object but not its query parameters.
- The API returns the first 25 log items, as the API reference states.
- Read one item in full with logItem.
Limitations
- Does not send limit, skip or any other query parameter, so it returns only the first 25 log items. The Java Management SDK has no way to read later pages of the organization log in 1.16.0.
Example
Basic usage: read the audit log
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.organization.Organization;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class ReadOrganizationLog {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
client.login("<EMAIL>", "<PASSWORD>");
Organization organization = client.organization("<ORGANIZATION_UID>");
Response<ResponseBody> response = organization.logsDetails().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());
}
}removeUsers
removeUsers builds the request that removes users from this organization by email address.
| Name | Type | Description |
|---|---|---|
| body (required) | JSONObject | Request body with the users to remove. |
| body.emails (required) | List of String | Email addresses of the users to remove. |
Returns: Call<ResponseBody>. The request that removes the users, sent when you call execute().
Validation
- Throws NullPointerException if the organization has no UID, as after client.organization() without an argument, because the request path needs the UID.
- removeUsers does not check body. A null body makes execute() throw IllegalArgumentException.
- 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
Warning The users lose access to the organization and its stacks when the request succeeds. To undo it, invite them again with inviteUser.
- One execute() sends one Remove users from organization request (DELETE /organizations/{organization_uid}/share) with body as the JSON body.
- removeUsers sends the headers of this object but not its query parameters.
- Only the owner or an admin of the organization can remove users, as the API reference states.
Example
Basic usage: remove two users
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.organization.Organization;
import java.util.Arrays;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class RemoveOrganizationUsers {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
client.login("<EMAIL>", "<PASSWORD>");
Organization organization = client.organization("<ORGANIZATION_UID>");
JSONObject body = new JSONObject();
body.put("emails", Arrays.asList("[email protected]", "[email protected]"));
Response<ResponseBody> response = organization.removeUsers(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());
}
}resendInvitation
resendInvitation builds the request that sends a pending organization invitation again.
| Name | Type | Description |
|---|---|---|
| shareUid (required) | String | UID of the pending invitation. |
Returns: Call<ResponseBody>. The request that resends the invitation, sent when you call execute().
Validation
- Throws NullPointerException if the organization has no UID, as after client.organization() without an argument, because the request path needs the UID.
- resendInvitation does not check shareUid. A null value makes execute() throw IllegalArgumentException.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One execute() sends one Resend pending Organization invitation request (GET /organizations/{organization_uid}/share/{share_uid}/resend_invitation).
- resendInvitation sends the headers of this object but not its query parameters.
- Only the owner or an admin of the organization can resend an invitation, as the API reference states.
- Get the invitation UID from allInvitations.
Example
Basic usage: resend one invitation
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.organization.Organization;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class ResendInvitation {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
client.login("<EMAIL>", "<PASSWORD>");
Organization organization = client.organization("<ORGANIZATION_UID>");
String shareUid = args[0]; // the invitation UID from allInvitations
Response<ResponseBody> response = organization.resendInvitation(shareUid).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 builds the request that lists the roles that users hold in this organization.
| Name | Type | Description |
|---|---|---|
| limit | int | Maximum number of items to return. |
| skip | int | Number of items to skip. |
| asc | String | Field UID to sort by in ascending order. |
| desc | String | Field UID to sort by in descending order. |
| include_count | boolean | true adds the total count to the response. |
| include_stack_roles | boolean | true adds the stack-level roles to the response. |
Returns: Call<ResponseBody>. The request for the organization's roles, sent when you call execute().
Validation
- Throws NullPointerException if the organization has no UID, as after client.organization() without an argument, because the request path needs the UID.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One execute() sends one Get all roles in an Organization request (GET /organizations/{organization_uid}/roles), with the headers and query parameters of this object.
- The response body is the raw JSON of the API.
- Use a role UID from the response in the body of inviteUser.
Example
Basic usage: list the roles
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.organization.Organization;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class ListOrganizationRoles {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
client.login("<EMAIL>", "<PASSWORD>");
Organization organization = client.organization("<ORGANIZATION_UID>");
Response<ResponseBody> response = organization.roles().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}All parameters: include stack roles and the count
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.organization.Organization;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class ListAllRoles {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
client.login("<EMAIL>", "<PASSWORD>");
Organization organization = client.organization("<ORGANIZATION_UID>");
Response<ResponseBody> response = organization
.addParam("limit", 20)
.addParam("skip", 0)
.addParam("desc", "created_at")
.addParam("include_count", true)
.addParam("include_stack_roles", true)
.roles()
.execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}stacks
stacks builds the request that lists the stacks in this organization.
| Name | Type | Description |
|---|---|---|
| limit | int | Maximum number of items to return. |
| skip | int | Number of items to skip. |
| asc | String | Field UID to sort by in ascending order. |
| desc | String | Field UID to sort by in descending order. |
| include_count | boolean | true adds the total count to the response. |
| typeahead | String | Text that filters stacks by name. |
Returns: Call<ResponseBody>. The request for the organization's stacks, sent when you call execute().
Validation
- Throws NullPointerException if the organization has no UID, as after client.organization() without an argument, because the request path needs the UID.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One execute() sends one Get all stacks in an Organization request (GET /organizations/{organization_uid}/stacks), with the headers and query parameters of this object.
- The response body is the raw JSON of the API.
Example
Basic usage: list the stacks
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.organization.Organization;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class ListOrganizationStacks {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
client.login("<EMAIL>", "<PASSWORD>");
Organization organization = client.organization("<ORGANIZATION_UID>");
Response<ResponseBody> response = organization.stacks().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}All parameters: search the stacks by name
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.organization.Organization;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class SearchOrganizationStacks {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
client.login("<EMAIL>", "<PASSWORD>");
Organization organization = client.organization("<ORGANIZATION_UID>");
Response<ResponseBody> response = organization
.addParam("limit", 25)
.addParam("skip", 25)
.addParam("asc", "name")
.addParam("include_count", true)
.addParam("typeahead", "blog")
.stacks()
.execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}transferOwnership
transferOwnership builds the request that offers the ownership of this organization to another user by email.
| Name | Type | Description |
|---|---|---|
| body (required) | JSONObject | Request body with the new owner. |
| body.transfer_to (required) | String | Email address of the new owner. |
Returns: Call<ResponseBody>. The request that starts the ownership transfer, sent when you call execute().
Validation
- Throws NullPointerException if the organization has no UID, as after client.organization() without an argument, because the request path needs the UID.
- transferOwnership does not check body. A null body makes execute() throw IllegalArgumentException.
- 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
Warning When the new owner accepts the invitation, you lose ownership of the organization. Only the new owner can transfer it back.
- One execute() sends one Transfer Organization ownership request (POST /organizations/{organization_uid}/transfer-ownership) with body as the JSON body.
- transferOwnership sends the headers of this object but not its query parameters.
- The API sends an email invitation to the user. The ownership moves when that user accepts it, as the API reference states.
Example
Basic usage: offer ownership to a colleague
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.organization.Organization;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class TransferOwnership {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
client.login("<EMAIL>", "<PASSWORD>");
Organization organization = client.organization("<ORGANIZATION_UID>");
JSONObject body = new JSONObject();
body.put("transfer_to", "[email protected]");
Response<ResponseBody> response = organization.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());
}
}