Embed Entries or Assets

Contentstack allows you to embed entries and assets directly within the JSON Rich Text Editor field. These embedded items are dynamically updated whenever the source entry or asset is modified, ensuring your content stays in sync.

The JSON RTE field lets you embed entries inline within the flow of text, as a separate content block, or as a dynamic hyperlink.

Note The embed feature is only available in the Advanced and Custom Rich Text Editor fields. Basic RTE does not support this option.

When you embed entries or assets in the JSON RTE, the data of the embedded items is stored directly, not just a reference. As a result:

• Updates to the original entries or assets are not reflected automatically in the RTE content.
• The RTE field will continue to display the original embedded data.

However, the latest versions of these embedded items can be accessed through the _embedded_items section.

Note The RTE field does not auto-replace old data with the updated versions from _embedded_items. It is the user's responsibility to update the content as needed.

By embedding entries, you can dynamically insert structured content such as product listings, event details, or blog excerpts.

In the Custom editor type, enable the Embed Objects option and select the content type from which you want to embed entries.

Click to enlarge

Here are some examples of how embedded entries can enhance content:

1. Inline Entries: Embed dynamic values like working titles or links triggering modal pop-ups.
2. Block Entries: Add rich elements like image carousels, product lists, or surveys as content blocks.
3. Hyperlinks: Create links that reflect changes in the linked entries automatically.

Note When embedding localized entries, updates to localized versions must be applied manually. For example, if a "Blog" entry is linked within the "Home" entry in English and later localized to Arabic, you’ll need to manually update the Arabic "Home" entry to link to the Arabic version of the "Blog."

To embed an entry within your JSON RTE, log in to your Contentstack account and perform the steps given below:

1. Navigate to the desired stack, then click the Entries icon.
2. Create a new entry or open an existing one containing a JSON RTE field.
3. In the JSON RTE field, click the Embed Entry icon in the toolbar.
4. In the Select Entry modal that appears, select the content type from which you want to embed an entry.
5. From the list of available entries, select the entry.
6. Choose the Embed Type:
   1. Block Embed: Embeds the entry as a standalone block.
   2. Inline Embed: Embeds the entry within a text flow.
7. Click Embed Selected Entry to embed it into the RTE.

Note You can embed up to 100 entries in a single RTE field.

Embedding assets enriches your content with media that updates automatically when changed in the Asset Manager, ensuring consistency.

Assets can be embedded by default into the JSON RTE field. In the Custom editor type, select the Asset option.

Here are some examples of how embedded assets can enhance content:

1. Displayable Component: Images or media are automatically updated on the frontend when modified in the Asset Manager.
2. Downloadable Files: Provide links to PDFs or other reference files for download.

To embed an asset within your JSON RTE, log in to your Contentstack account and perform the steps given below:

1. Navigate to the desired stack, then click the Entries icon.
2. Create a new entry or open an existing one containing a JSON RTE field.
3. In the JSON RTE field, click the Asset icon in the toolbar.
4. From the dropdown menu, select Choose from assets or Upload new asset(s).
5. Choose from Assets:
   • In the Select Asset modal, browse or search for the desired asset.
   • Select the asset you wish to embed.
6. Upload New Asset(s):
   • In the Upload Asset modal, click the “+” icon to create a new folder if needed.
   • Select files from your system (supported formats: images, PDFs, videos).
7. Choose the Embed Type:
   • Block Embed: Embeds the asset as a standalone block.
   • Inline Embed: Embeds the asset within a text flow.
8. Click Add Selected Asset to embed it into the RTE.

Note If an asset is deleted from the library later, any linked instances in the JSON output will become invalid.

You can edit an embedded asset directly within the JSON RTE:

1. Hover over the embedded asset and click the Edit icon.
2. The Edit Image modal appears with the following options:
   • Alt Text: Provide alternative text for better accessibility and SEO.
   • Alignment: Set the asset alignment (e.g., left, center, right).
   • Caption: Add a descriptive caption beneath the asset.
   • Embed Link: Insert a URL to hyperlink the asset.
   • Auto-adjust dimensions: Automatically adjust dimensions based on the RTE width, or manually enter Width and Height.
   • Lock aspect ratio: Maintain the original aspect ratio during resizing.
   • Open link in a new tab: Enable or disable link target behavior.
   • Inline image: Display the asset inline with the text.
3. Click Save.
   Click to enlarge

   Note These edits affect only the current embed instance and do not modify the original asset in the Asset Manager.

When you embed an entry or asset in the JSON RTE, its details, such as URL and title, are captured at the time of saving. If the embedded item is updated or republished afterward, the RTE field does not automatically reflect those changes.

This gives you two options, depending on your use case:

• Original (as-saved) data: Use the values stored directly on the RTE node (node.attrs). This is the snapshot from when the item was embedded.
• Latest published data: Read the item from the _embedded_items section of the response. Fetch the entry with include_embedded_items[]=BASE or include_embedded_items[]=RECURSIVE, then match each embedded node by uid to the corresponding object in _embedded_items. This returns the entry or asset's currently published state.

If you use a Contentstack Utils SDK, this resolution is done for you. Read the resolved values from node.attrs._resolved, and treat the legacy node.attrs['asset-link'] and similar properties as a soft-deprecated fallback. Match by uid manually only when you consume the Content Delivery API or the Content Management API directly.

An asset was embedded in an RTE field, then later renamed or replaced in its asset library.

The original value, stored on the RTE node as a snapshot from when it was embedded:

{
  "type": "asset",
  "attrs": {
    "asset-uid": "blt1a2b3c4d5e6f",
    "asset-link": "https://images.contentstack.io/v3/assets/.../photo-v1.jpg",
    "asset-name": "Old Photo Name",
    "content-type-uid": "sys_assets",
    "display-type": "display"
  }
}

The latest value, which is the same asset's current state returned in _embedded_items when you fetch the entry with include_embedded_items[]=BASE:

{
  "_embedded_items": {
    "rte_field": [
      {
        "uid": "blt1a2b3c4d5e6f",
        "_content_type_uid": "sys_assets",
        "url": "https://images.contentstack.io/v3/assets/.../photo-v2.jpg",
        "title": "New Photo Name"
      }
    ]
  }
}

To resolve the latest value for each embedded node:

entry = fetchEntry(entryUid, { include_embedded_items: ["BASE"] })

for each rteField in entry:
  for each node in rteField.nodes where node.type is "entry" or "asset":
    originalValue = node.attrs                       // snapshot from save time
    embeddedItems = entry._embedded_items[rteField.name] || []
    latestValue   = embeddedItems.find(item => item.uid === node.attrs["asset-uid" or "entry-uid"])
    render(latestValue || originalValue)              // prefer latestValue; fall back if item was deleted

Note If an embedded entry itself embeds more items, use include_embedded_items[]=RECURSIVE with embedded_items_depth to resolve the whole chain in one request. Refer to the Retrieve Nested Embedded Items with RECURSIVE section below.

Passing include_embedded_items[]=BASE, which is the existing behavior, returns first-level embedded items. To retrieve nested embedded items, set include_embedded_items[] to RECURSIVE. For example, an entry embeds an entry that embeds an asset:

Entry
└── JSON RTE
    └── Embedded entry
        └── Embedded asset

Using RECURSIVE retrieves the embedded entry and its nested asset in the same response:

include_embedded_items[]=RECURSIVE

Contentstack resolves the nested items and returns them in the _embedded_items object.

Use embedded_items_depth with RECURSIVE to specify how many levels of nested embedded items to retrieve:

include_embedded_items[]=RECURSIVE&embedded_items_depth=2

• If you don't specify embedded_items_depth, the depth defaults to 5.
• The maximum supported depth is 5.
• Values greater than 5 are clamped to 5.
• Use the smallest depth that meets your need to avoid unnecessarily increasing the response size.

Recursive retrieval increases response size because more embedded items are included at each level. Contentstack deduplicates repeated references, so real-world payloads are often smaller.

When you render JSON RTE content with a Contentstack Utils SDK, the SDK resolves embedded entry and asset metadata from _embedded_items and exposes it at node.attrs._resolved. Read resolved values from there. The legacy node.attrs['asset-link'] and similar properties remain readable as a soft-deprecated fallback.

• Passing include_embedded_items[]=BASE, or omitting the parameter, returns the same response as before. No migration is required.
• RECURSIVE is opt-in and available only for GET or read operations. There are no changes to Content Management API POST or PUT requests.
• The Content Delivery API resolves the published state, and the Content Management API resolves the latest or draft state.
• Access-control checks are applied to embedded items at every depth.
• RECURSIVE is available to any API key with entry read access.

Embedding entries and assets within the JSON RTE enriches your content with dynamic and structured elements. By following this guide, you can seamlessly integrate entries and assets, whether as inline components, blocks, or hyperlinks.