Contentstack App SDK API Reference

The Contentstack App SDK allows you to build custom applications that interact directly with Contentstack’s content management interface. Developed in TypeScript, it provides type-safe methods to access content data, manage UI extensions, and interact with Contentstack’s core APIs. These applications run within the Contentstack interface, using the SDK to access contextual data, UI locations, and platform APIs.

This quickstart uses a Custom Field as an example to demonstrate SDK installation and initialization. You can use this initialization pattern in other UI locations as well.

Install the Contentstack App SDK in your project using npm. The SDK includes initialization methods and context objects for your app to communicate with Contentstack.

npm install @contentstack/app-sdk

Once installed, initialize the SDK to access the Custom Field context, which provides access to the current entry and field values.

import { ContentstackAppSDK } from '@contentstack/app-sdk';

const sdk = await ContentstackAppSDK.init();
const customField = sdk.location.CustomField;

if (customField) {
  const field = customField.field;
  const entry = customField.entry;
}

After initializing the SDK, you can use the available UI location APIs to build custom behavior for your app. Refer to the Overview of UI Locations section to explore supported locations and their capabilities.

The ContentstackAppSDK class provides access to all SDK properties and methods. Use it to initialize your app and interact with Contentstack’s UI locations, environment, and configuration.

location

The location property gives access to all UI locations.

const customField = sdk.location.CustomField;
const sidebar = sdk.location.SidebarWidget;

region

The region property returns the Contentstack region where the app is running.

console.log(sdk.region); // "NA", "EU", "AU"

version

The version property returns the current version of the installed app.

console.log(sdk.version); // 1

init()

The init() method initializes the SDK and returns a configured instance.

Returns: Promise<ContentstackAppSDK>

const sdk = await ContentstackAppSDK.init();

The Contentstack App SDK provides multiple UI locations that allow apps to integrate with different parts of the Contentstack interface. These locations are organized below by functional area.

Note: The availability of UI locations and APIs depends on the app’s permissions, the user’s role, and the context in which the app is running. Some APIs may require management-level access or may not be available in all UI locations.

The DashboardWidget UI location integrates with the Contentstack dashboard to provide stack-level functions.

const dashboard = sdk.location.DashboardWidget;
if (dashboard) {
  const stack = dashboard.stack;
  const frame = dashboard.frame;
}

It supports the following objects:

• Stack
• Frame

The FullPage object enables full-page applications within the Contentstack interface for handling complex workflows or data operations.

const fullPage = sdk.location.FullPage;
if (fullPage) {
  const stack = fullPage.stack;
  const contentTypes = await stack.getContentTypes();
}

It supports only the Stack core object.

The GlobalFullPageLocation object provides cross-stack functionality for global applications that operate across multiple stacks or organizations.

const globalFullPage = sdk.location.GlobalFullPageLocation;
if (globalFullPage) {
  const currentOrg = globalFullPage.currentOrganization;
  console.log('Current organization:', currentOrg);
}

The currentOrganization property provides the current organization details.

const currentOrg = globalFullPage.currentOrganization;
console.log('Organization name:', currentOrg.name);
console.log('Organization UID:', currentOrg.uid);

The AppConfigWidget object enables app configuration and settings management within the Contentstack UI.

const appConfig = sdk.location.AppConfigWidget;
if (appConfig) {
  const stack = appConfig.stack;
  const installation = appConfig.installation;
}

It supports only the stack core object.

The installation property manages app installation data, including retrieval and updates.

const installation = appConfig.installation;
const data = await installation.getInstallationData();
await installation.setInstallationData(newData);
installation.setValidity(true);

The CustomField object extends field functionality with custom validation and input components.

const customField = sdk.location.CustomField;
if (customField) {
  const field = customField.field;
  const entry = customField.entry;
  const stack = customField.stack;
  const frame = customField.frame;
}

It supports the following core objects:

• Stack
• Frame
• Field
• Entry

The fieldConfig property provides access to the configuration and metadata of a custom field. It enables you to retrieve details such as field settings, data type, and other configuration parameters defined in the content type.

const fieldConfig = customField.fieldConfig;
console.log('Field config:', fieldConfig);
console.log('Field type:', fieldConfig.type);

The SidebarWidget UI location integrates with entry sidebars to provide contextual tools and information for content editors.

const sidebar = sdk.location.SidebarWidget;
if (sidebar) {
  const entry = sidebar.entry;
  const stack = sidebar.stack;
}

It supports the following core objects:

• Entry
• Stack

The FieldModifierLocation UI location enables field data transformation and manipulation.

const fieldModifier = sdk.location.FieldModifierLocation;
if (fieldModifier) {
  const field = fieldModifier.field;
  const entry = fieldModifier.entry;
  const stack = fieldModifier.stack;
  const frame = fieldModifier.frame;
}

It supports the following core objects:

• Entry
• Stack
• Frame
• Field

The ContentTypeSidebarWidget object provides content type management and schema tools within the Contentstack UI.

const contentTypeSidebar = sdk.location.ContentTypeSidebarWidget;
if (contentTypeSidebar) {
  const contentTypeData = contentTypeSidebar.getData();
  contentTypeSidebar.onSave((updatedType) => {
    console.log('Content type updated:', updatedType);
  });
}

currentContentType

The currentContentType property retrieves the current content type object directly.

const contentType = contentTypeSidebar.currentContentType;
console.log('Current content type:', contentType);

getData()

The getData() method retrieves the current content type data.

const contentTypeData = contentTypeSidebar.getData();
console.log('Content type:', contentTypeData.title);
console.log('Schema:', contentTypeData.schema);

onSave(callback)

The onSave() method listens for content type save events.

contentTypeSidebar.onSave((updatedContentType) => {
  console.log('Content type saved:', updatedContentType);
  // Handle the updated content type
});

The AssetSidebarWidget UI location integrates with asset management interfaces in the Contentstack UI.

const assetSidebar = sdk.location.AssetSidebarWidget;
if (assetSidebar) {
  const assetData = assetSidebar.getData();
  await assetSidebar.setData({ title: 'New Asset Title' });
  assetSidebar.onSave((updatedAsset) => {
    console.log('Asset saved:', updatedAsset);
  });
}

The currentAsset property retrieves the current asset object directly.

const asset = assetSidebar.currentAsset;
console.log('Current asset:', asset);

The getData method retrieves the current asset data.

const assetData = assetSidebar.getData();
console.log('Asset title:', assetData.title);
console.log('Asset URL:', assetData.url);

The setData method sets data for the current asset.

await assetSidebar.setData({ 
  title: 'New Asset Title',
  description: 'Updated description'
});

The syncAsset method synchronizes the asset with the parent application.

await assetSidebar.syncAsset();

The updateWidth method updates the width of the Asset Sidebar widget.

await assetSidebar.updateWidth(400);

The replaceAsset method replaces the current asset with a new file.

const fileInput = document.getElementById('fileInput');
const file = fileInput.files[0];
await assetSidebar.replaceAsset(file);

The onSave method listens for asset save events.

assetSidebar.onSave((savedAsset) => {
  console.log('Asset saved:', savedAsset);
});

The onChange method listens for asset change events.

assetSidebar.onChange((changedAsset) => {
  console.log('Asset changed:', changedAsset);
});

The onPublish method listens for asset publish events.

assetSidebar.onPublish((publishedAsset) => {
  console.log('Asset published:', publishedAsset);
});

The onUnPublish method listens for asset unpublish events.

assetSidebar.onUnPublish((unpublishedAsset) => {
  console.log('Asset unpublished:', unpublishedAsset);
});

The Rich Text Editor (RTE) provides extensibility through plugins and context-based APIs that enable developers to customize editing experiences and interact with entry data.

The RTEPlugin function creates custom plugins for the Rich Text Editor.

rtePlugin(id, config)

The rtePlugin method registers a plugin with the RTE system.

import { rtePlugin } from '@contentstack/app-sdk';

rtePlugin('my-plugin', (rte) => {
  return {
    title: 'My Plugin',
    icon: '',
    render: (props) => {
      // Plugin implementation
    }
  };
});

The RTELocation object provides access to the RTE context and entry data within rich text fields.

const rteLocation = sdk.location.RTELocation;
if (rteLocation) {
  const entry = rteLocation.entry;
  const entryData = entry.getData();
}

It supports only the entry core object:

Core objects represent the primary data and context models used by the Contentstack App SDK. They define the main interfaces through which apps access contextual information and interact with Contentstack using structured properties, methods, and event callbacks.

The availability of specific core objects depends on the active UI location. Each object exposes a well-defined API surface that supports data access, operations, and event-driven behavior within the scope of that location.

The stack object provides methods to access, manage, and retrieve stack-level data and related entities such as content types, entries, assets, and workflows.

Example:

const stack = sdk.stack;

The following section explains the different methods available in the stack object.

getData()

The getData() method retrieves the data of the current stack.

const stackData = stack.getData();
console.log('Stack name:', stackData.name);
console.log('Stack UID:', stackData.uid);

getAllStacks(orgUid?, params?)

The getAllStacks() method retrieves all stacks in the current organization.

const allStacks = await stack.getAllStacks();
const orgStacks = await stack.getAllStacks('org_uid');

getContentType(uid, params?)

The getContentType() method retrieves data of a single content type.

const contentType = await stack.getContentType('content_type_uid');

getContentTypes(query?, params?)

The getContentTypes() method retrieves data of all content types in the stack.

const contentTypes = await stack.getContentTypes();
const filteredTypes = await stack.getContentTypes({ title: { $regex: 'blog' } });

getEntries(contentType, params?)

The getEntries() method retrieves entries of a specific content type.

const entries = await stack.getEntries('content_type_uid');
const publishedEntries = await stack.getEntries('content_type_uid', { publish: true });

getAssets(query?, params?)

The getAssets() method retrieves assets from the stack.

const assets = await stack.getAssets();
const images = await stack.getAssets({ content_type: 'image/*' });

getGlobalField(uid, params?)

The getGlobalField() method retrieves details of a specific global field.

const globalField = await stack.getGlobalField('global_field_uid');

getGlobalFields(query?, params?)

The getGlobalFields() method retrieves details of all global fields in the stack.

const globalFields = await stack.getGlobalFields();

getReleases(query?, params?)

The getReleases() method retrieves details of all releases in the stack.

const releases = await stack.getReleases();

getPublishes(query?, params?)

The getPublishes() method retrieves details of the publish queue in the stack.

const publishQueue = await stack.getPublishes();

getEnvironment(name, params?)

The getEnvironment() method retrieves details of a specific environment.

const environment = await stack.getEnvironment('production');

getEnvironments(query?, params?)

The getEnvironments() method retrieves details of all environments in the stack.

const environments = await stack.getEnvironments();

getLocale()

The getLocale() method retrieves details of a specific locale.

const locale = await stack.getLocale('en-us');

getLocales()

The getLocales() method retrieves details of all locales in the stack.

const locales = await stack.getLocales();

getWorkflow(uid, params?)

The getWorkflow() method retrieves details of a specific workflow.

const workflow = await stack.getWorkflow('workflow_uid');

getWorkflows(query?, params?)

The getWorkflows() method retrieves all workflows in the stack.

const workflows = await stack.getWorkflows();

getAllBranches()

The getAllBranches() method retrieves all branches in the current stack.

const branches = stack.getAllBranches();

getCurrentBranch()

The getCurrentBranch() method retrieves details of the current branch.

const currentBranch = stack.getCurrentBranch();

getVariantById(variant_uid)

The getVariantById() method retrieves details of a specific variant group.

const variant = await stack.getVariantById('variant_uid');

getManagementTokens()

The getManagementTokens() method retrieves details of all management tokens for the stack.

const tokens = await stack.getManagementTokens();

search(queries, apiKey?)

The search method retrieves search results based on the user query.

const searchResults = await stack.search({
  type: 'entries',
  query: { content_type: 'blog_post' },
  limit: 10
});

The entry object provides access to entry-specific data, operations, and event handling. It is supported in entry-related UI locations such as CustomField, SidebarWidget, RTELocation, and FieldModifier.

Properties

content_type

The content_type property retrieves the content type of the current entry.

const contentType = entry.content_type;
console.log('Content type:', contentType.title);

locale

The locale property retrieves the locale of the current entry.

const locale = entry.locale;
console.log('Entry locale:', locale);

Methods

getData()

The getData() method retrieves the data of the current saved entry.

const entryData = entry.getData();

getDraftData()

The getDraftData() method retrieves the draft data of the current unsaved entry and returns an empty object if no changes exist.

const draftData = await entry.getDraftData();
console.log('Draft data:', draftData);

getField(uid, options?)

The getField() method retrieves the field object for the saved data. useUnsavedSchema affects schema resolution, not the field value.

const titleField = entry.getField('title');
const fieldWithUnsavedSchema = entry.getField('title', { useUnsavedSchema: true });

getPropertySafely(obj, key)

The getPropertySafely() method safely retrieves the value of a property from an object to prevent prototype pollution vulnerabilities.

const value = entry.getPropertySafely(dataObject, 'propertyName');

Events

onSave(callback)

The onSave event is invoked when the entry is saved.

entry.onSave((savedEntry) => {
  console.log('Entry saved:', savedEntry);
});

onChange(callback)

The onChange event executes a callback when the entry is updated.

entry.onChange((unresolvedEntry, resolvedEntry) => {
  console.log('Entry changed:', unresolvedEntry);
  console.log('Resolved entry:', resolvedEntry);
});

onPublish(callback)

The onPublish event executes a callback when the entry is published.

entry.onPublish((publishDetails) => {
  console.log('Entry published:', publishDetails);
});

onUnPublish(callback)

The onUnPublish event executes a callback when the entry is unpublished.

entry.onUnPublish((publishDetails) => {
  console.log('Entry unpublished:', publishDetails);
});

The Field object provides access to individual field data, schema information, and field-level operations. It is available only in field-level UI locations such as CustomField and FieldModifier.

Properties

uid

The uid property retrieves the unique identifier of the field.

const fieldUid = field.uid;
console.log('Field UID:', fieldUid);

data_type

The data_type property retrieves the data type of the field.

const dataType = field.data_type;
console.log('Field data type:', dataType);

schema

The schema property retrieves the schema definition of the field.

const fieldSchema = field.schema;
console.log('Field schema:', fieldSchema);

Methods

getData(options?)

The getData() method retrieves the data of the current field.

const fieldData = field.getData();
const resolvedData = field.getData({ resolved: true });

setData(data)

The setData() method sets the data for the current field.

await field.setData('new value');

setFocus()

The setFocus() method sets the focus on a field when an app is in use, displaying user presence and highlighting the custom field currently accessed in the Contentstack UI.

await field.setFocus();

onChange(callback)

The onChange() method registers a callback that runs when the field’s data is programmatically updated by another app or extension using setData().

field.onChange((data) => {
  console.log('Field changed:', data);
});

The frame object provides window management and resizing capabilities for UI locations. It is supported in UI locations such as DashboardWidget, GlobalFullPageLocation, and FieldModifierLocation.

The following section explains the different methods available in the frame object.

enableResizing()

The enableResizing() method activates the resize button, allowing users to adjust the window size of a Dashboard Widget.

const frame = dashboard.frame;
await frame.enableResizing();

Returns: Promise<void>

updateHeight(height?)

The updateHeight() method updates the widget height in the Contentstack UI. If no height is provided, it automatically adjusts based on the scroll height.

const frame = customField.frame;
await frame.updateHeight(600);

Parameters:

• height (optional): The desired height of the iframe window in pixels

Returns: Promise<void>

enableAutoResizing()

The enableAutoResizing() method enables automatic resizing of the widget height.

const frame = fieldModifier.frame;
frame.enableAutoResizing();

Returns: Window — The context of the Window class

disableAutoResizing()

The disableAutoResizing() method disables automatic resizing of the widget height.

const frame = fieldModifier.frame;
frame.disableAutoResizing();

Returns: Window — The context of the Window class

onDashboardResize(callback)

The onDashboardResize() method executes a callback whenever a Dashboard Widget is maximized or minimized.

const frame = dashboard.frame;
frame.onDashboardResize((state) => {
  console.log('Dashboard resized:', state);
});

Parameters:

• callback: The function to be called when a Dashboard Widget is maximized or minimized

Returns: boolean — true if the operation completes successfully; otherwise false

enablePaddingTop()

The enablePaddingTop method adds padding to the top of the Dashboard Widget.

const frame = dashboard.frame;
await frame.enablePaddingTop();

Returns: Promise<void>

disablePaddingTop()

The disablePaddingTop method removes the padding previously added to the top of the Dashboard Widget.

const frame = dashboard.frame;
await frame.disablePaddingTop();

Returns: Promise<void>

updateDimension(dimension?)

The updateDimension method updates the height and width of the UI location in the Contentstack UI. If no values are provided, it updates based on the current dimensions.

const frame = fieldModifier.frame;
await frame.updateDimension({ height: 400, width: 300 });

Parameters:

• dimension (optional): Object with height and width properties

Returns: Promise<void>

closeModal()

The closeModal method closes the app modal window.

const frame = fieldModifier.frame;
await frame.closeModal();

Returns: Promise<void>

The Store object provides methods to manage key-value data storage within the app environment. This enables apps to persist and retrieve data across sessions without relying on external storage or manual state management.

The following section explains the different methods available in the store object.

get(key)

The get() method retrieves stored data by key.

const value = await store.get('userPreferences');

set(key, value)

The set() method sets data for a specified key.

await store.set('userPreferences', { theme: 'dark' });

getAll()

The getAll() method retrieves all stored data.

const allData = await store.getAll();

remove(key)

The remove() method removes stored data by key.

await store.remove('userPreferences');

clear()

The clear() method clears all stored data.

await store.clear();

The SDK provides structured error handling for all operations to ensure reliable execution and clear reporting of failures.

Errors can be managed using standard try...catch blocks to handle issues such as initialization errors, invalid operations, or data update failures.

try {
  const sdk = await ContentstackAppSDK.init();
  const customField = sdk.location.CustomField;
  
  if (customField) {
    const field = customField.field;
    await field.setData('new value');
  }
} catch (error) {
  console.error('SDK Error:', error);
}

The following examples show how to work with fields, entries, and stack data in a plugin environment.

The following pattern allows you to respond to user actions such as field value updates or entry saves, and update the UI when entry data changes.

const entry = customField.entry;

entry.onChange((unresolved, resolved) => {
  console.log('Entry changed:', resolved);
});

entry.onSave((savedEntry) => {
  console.log('Entry saved:', savedEntry);
});

This pattern lets you read or update the current field’s value programmatically.

const field = customField.field;
const currentData = field.getData();
await field.setData('new value');

This pattern is useful for fetching related content or assets directly from your app’s context.

const stack = customField.stack;
const contentTypes = await stack.getContentTypes();
const assets = await stack.getAssets();

Note: The App SDK does not provide a direct method to fetch entries by content type from the stack context.

1. Location Validation: Always check if a location exists before use.
2. TypeScript: Leverage TypeScript for a better development experience.
3. Error Handling: Implement proper error handling in production.
4. Testing: Test applications across different UI locations.
5. Design Consistency: Follow Contentstack's design guidelines.

The SDK provides comprehensive TypeScript definitions:

• ContentstackAppSDK – Main SDK class
• UILocation – UI location interfaces
• Entry – Entry object interface
• Field – Field object interface
• Stack – Stack object interface
• Store – Store object interface