When you retrieve or update language variants or assets, you will work with a set of elements. The set contains the elements as defined in the content type or asset type. The elements come in the form of key-value pairs and contain only information about their values, not their type.Currently, only the taxonomy element is supported in the assets.
The rich text element stores formatted HTML content that can include embedded assets, components, content items, and links. The following sections describe the rich text element structure and the HTML syntax for its content.
About element identifiersIn API responses, the Management API will always reference content elements with their internal IDs. When creating or updating language variants or assets via the API, you can reference content elements by their internal IDs or codenames.
element
required · object
Show child attributes
element
required · object
Show child attributes
element
required · object
Show child attributes
element
required · object
Show child attributes
element
required · object
Show child attributes
element
required · object
Show child attributes
element
required · object
Show child attributes
element
required · object
Show child attributes
element
required · object
Show child attributes
element
required · object
Show child attributes
value[]
required · array · unique items
value
required · string · nullable · max. 200000 chars
searchable_value
string · nullable · max. 200000 chars
value
required · string · nullable · date-time
display_timezone
string · nullable
Default value:
null
value[]
required · array
Show child attributes
value[]
required · array · unique items
Show child attributes
value
required · number · nullable · Floating-point number
value[]
required · array
Show child attributes
value[]
required · array · unique items
Show child attributes
value
required · string · nullable · max. 100000 chars
mode
required · string
value
string
id
string · uuid
codename
string · write-only
external_id
string · write-only
renditions[]
array · max. 1 items
Show child attributes
HTML5 elements allowed in rich text
Assets in rich text
Components in rich text
Content items in rich text
Links in rich text
Lists in rich text
Tables in rich text
Rich text element
The rich text value can contain specific HTML elements, tags, and attributes and must form a valid HTML5 fragment. Only the documented HTML attributes are supported. When transforming HTML to JSON, make sure to escape all double quotes.The following HTML elements must be used at the top level in rich text content. They can also be used within a table cell <td>.
Assets in rich text elements are defined by the <figure> block element. The <figure> element specifies its asset using one of the following attributes: data-asset-id, data-asset-codename, or data-asset-external-id.When updating rich text values, the <figure> element can optionally include the <img> element. In such cases, the <img> element must specify the asset using the same data attribute as the parent <figure> element. For example, if the <figure> element specifies the asset using data-asset-external-id, the <img> element must use data-asset-external-id
Components in rich text are defined by the <object> block element. The <object> element requires the type, data-type, and data-id attributes.
For each component in the text, the rich text object's components property must hold a matching component object. When specifying components in the rich text's value property, you need to provide a unique ID (GUID) for the data-id attribute of each component.If the inserted component contains a rich text element, the rich text element may contain more components. These nested components may contain another rich text element with more components, and so on. The components can be nested up to 6 levels deep.
Content items in rich text are defined by the <object> block element. The <object> element requires the attributes type, data-type, and either data-codename, data-id, or data-external-id. The data-external-id attribute can also reference an object that has not yet been imported into Kontent.ai. Find more about using external IDs for imported content.
Links in rich text are defined as the <a> element, for example, <a href="#">Link</a>. These links can be used for web URLs, email addresses, assets, and content items. For each of the link types, the <a> element supports a different set of required and optional attributes.Links to URLs require the href attribute.Optionally, the link can specify a title and whether the link should be opened in a new browser window.
If the link should provide a title, the <a> element must specify the title attribute with a value.
If the link should open in a new window, the <a> element must specify the data-new-window attribute set to true.
Lists in rich text are defined as standard HTML lists, either ordered (<ol>) or unordered (<ul>). Each list item can contain another nested list, a piece of HTML formatted text, or be empty.
Tables in rich text elements are defined as standard HTML tables with the table cells and rows contained within the <tbody> element. Individual table cells (<td>) can contain either text with inline formatting elements, or top-level elements. The table cells and rows cannot be merged.
Reference to a specific object in the environment.
Reference to a specific object in the environment.
Reference to a specific object in the environment.
Reference to a specific object in the environment.
Reference to a specific object in the environment.
Reference to a specific object in the environment.
Reference to a specific object in the environment.
Reference to a specific object in the environment.
Reference to a specific object in the environment.
Reference to a specific object in the environment.
The <thead> and <tfoot> tags are not supported.Individual table cells <td> can contain either text with inline formatting elements, or top-level elements.Nested tables are not supported inside table cells.
Content items and components are not supported inside table cells.
The following inline HTML elements can be used within the top-level elements and table cells.
Types
HTML elements
Notes
Bold text
<strong>...</strong>
The <b> tag is not supported.
Italic text
<em>...</em>
The <i> tag is not supported.
Superscript
<sup>...</sup>
as well. The
<img>
element might specify a
src
attribute but it's not required.
The data-asset-external-id attribute can also reference an object that doesn't exist, that is, an object that has not yet been imported into Kontent.ai. Find more about using external IDs for imported content.
Email links require the data-email-address attribute. Optionally, the link can contain the data-email-subject attribute.
Phone links require the data-phone-number attribute.
Links to assets require one of the following attributes: data-asset-id, data-asset-external-id, or data-asset-codename. The data-asset-external-id attribute can also reference an object that has not yet been imported into Kontent.ai. Find more about using external IDs for imported content.
Links to content items require one of the following attributes: data-item-id, data-item-external-id, or data-item-codename. The data-item-external-id attribute can also reference an object that has not yet been imported into Kontent.ai. Find more about using external IDs for imported contentt.
The value of asset elements is an array of Reference objects, each representing a single asset. Every asset can be referenced only once. You can also reference the asset's renditions by the renditions property. Renditions are specific to images only.When retrieving asset elements, the Management API will always reference assets with their internal IDs. When updating asset elements via the API, you can reference an asset by its internal ID or external ID. Also, you can reference a rendition by its internal ID or external ID.
The format depends on the custom element you use.When retrieving and updating custom elements, the format of the value will be identical for both GET and PUT operations.
Plain text searchable value used for searching in the content items list. Do not use any markup or JSON here to allow a correct search.When retrieving and updating custom elements, the format of the value will be identical for both GET and PUT operations.
Time in this element is interpreted as UTC and stored as an ISO-8601 formatted string.When retrieving and updating date & time elements, the format of the value will be identical for both GET and PUT operations.
IANA time zone name used to display time offset of the date & time element in the UI.The time zone doesn't modify the date specified in value.If omitted, the value defaults to null and the date in the UI is displayed in a local time zone.Obsolete values: "America/Ojinaga", "America/Scoresbysund", "Antarctica/Vostok", "Asia/Aqtobe", "Asia/Qyzylorda", "Europe/Kiev".
The value of Linked items elements is an array of Reference objects. Each reference represents a single content item. Every content item can be referenced only once.When retrieving Linked items elements, the Management API will always reference content items with their internal IDs. When updating Linked items elements via the API, you can reference a content item by its internal ID, codename, or external ID.
The value of Multiple choice elements is an array of Reference objects. Each reference represents one of the multiple choice options, each with a unique identifier.If the multiple choice element is configured as single option (i.e., dropdown menu), its value array must contain a reference to exactly one option. When configured as multiple option (i.e., checkboxes), the array can contain references to as many options as are defined in the content type. In case no option is selected, the value of the element will be an empty array.When retrieving Multiple choice elements, the Management API will always reference the multiple choice options with their internal IDs. When updating multiple choice elements via the API, you can reference an option by its internal ID or codename.
When retrieving and updating Number elements, the format of the value will be identical for both GET and PUT operations.
The value of Subpages elements is an array of Reference objects. Each reference represents a single content item. Every content item can be referenced only once.When retrieving Subpages elements, the Management API will always reference content items with their internal IDs. When updating Subpages elements via the API, you can reference a content item by its internal ID, codename, or external ID.
The value of taxonomy elements is an array of Reference objects. Each reference represents a taxonomy term of a specific taxonomy group. Every taxonomy term can be referenced only once.When retrieving taxonomy elements, the Management API will always reference taxonomy terms with their internal IDs. When updating taxonomy elements via the API, you can reference a taxonomy term by its internal ID, external ID, or codename.
When retrieving and updating text elements, the format of the value property will be identical for both GET and PUT operations.
Determines the element's mode of operation.
The element's value.
When upserting the element with the mode set to autogenerated, the value is ignored and can be omitted.
If the value is upserted, the element's mode changes to custom automatically.
The referenced object's codename. The value of the codename property must meet the conditions defined in rules for codenames.
The referenced object’s external ID. The value of the external_id property must not contain the following characters: /, ., ;.
The asset's renditions. Renditions are different editions of the original image used in Kontent.When you update a rendition via the API, it gets changed across all assets using this rendition. But when you do the same in the UI, for example, by duplicating an item that contains a rendition, changes to the rendition are not applied across the items.To remove a rendition, leave the array empty.
Reference to a specific object in the environment.
By default, if there is no text, the rich text value is a single empty paragraph: <p><br/></p>. The value can contain HTML formatted text, specific HTML elements, tags, and attributes, and must form a valid HTML5 fragment.For more information, see the list of supported HTML elements and their syntax.When retrieving rich text elements, the value property excludes unfinished AI requests and AI request errors but may include pending AI suggestions that appear as text without AI-specific identifiers.
A list of components used in the rich text's value.
{... "element": { "codename": "link_to_email_address" }, "value": "<p><a data-email-address=\"sales@kontent.ai\" data-email-subject=\"Can you show me around the Kontent.ai platform?\">reach out</a></p>"...}
{... "element": { "codename": "asset_linked_by_internal_id" }, "value": "<a data-asset-id=\"0b590263-3fe5-4773-afae-5a3f6e511e66\">link to an asset</a>"... "element": { "codename": "asset_linked_by_external_id" }, "value": "<a data-asset-external-id=\"custom-asset-identifier\">link to another asset</a>"... "element": { "codename": "asset_linked_by_codename" }, "value": "<a data-asset-codename=\"my_asset_codename\">link to asset by codename</a>"...}
JSON
{... "element": { "codename": "item_linked_by_internal_id" }, "value": "<a data-item-id=\"f4b3fc05-e988-4dae-9ac1-a94aba566474\">link to a content item</a>"... "element": { "codename": "item_linked_by_external_id" }, "value": "<a data-item-external-id=\"my-1337-article\">link to another content item</a>"... "element": { "codename": "item_linked_by_codename" }, "value": "<a data-item-codename=\"my_article\">link to a content item by codename</a>"...}
Inserting URL valuesWhen inserting URL values, the system might add the http:// prefix in case the provided URL is invalid or not safe. For example, URLs using the javascript:// protocol will be prefixed. URL values starting with /, ?, or # are allowed.Examples of how inserted URLs are stored:
http://example.com → http://example.com (no change)
https://example.com → https://example.com (no change)
ftp://example.com →
Other <a> attributes, such as target and rel, are not supported for URL links.
The API uses internal IDs for referencing objects. This means that the reference objects in the API responses will always use internal IDs.
The API uses internal IDs for referencing objects. This means that the reference objects in the API responses will always use internal IDs.
The API uses internal IDs for referencing objects. This means that the reference objects in the API responses will always use internal IDs.
The API uses internal IDs for referencing objects. This means that the reference objects in the API responses will always use internal IDs.
The API uses internal IDs for referencing objects. This means that the reference objects in the API responses will always use internal IDs.
The API uses internal IDs for referencing objects. This means that the reference objects in the API responses will always use internal IDs.
The API uses internal IDs for referencing objects. This means that the reference objects in the API responses will always use internal IDs.
The API uses internal IDs for referencing objects. This means that the reference objects in the API responses will always use internal IDs.
The API uses internal IDs for referencing objects. This means that the reference objects in the API responses will always use internal IDs.
The API uses internal IDs for referencing objects. This means that the reference objects in the API responses will always use internal IDs.
When you retrieve text elements, the value property excludes unfinished AI requests and AI request errors but may include pending AI suggestions that appear as text without AI-specific identifiers.
You can change the text element the URL slug depends on either in the UI or via the API.
Automatic vs. manual modeThe URL slug element can function in two modes, automatic and manual. When creating language variants in automatic mode, the system automatically generates the element's value based on the text element of your choice.If you modify the element's value directly (either in UI or via API), the element switches to the manual mode. In this mode, the element does not react to changes made to the dependent text element. Learn about creating SEO-friendly URLs in your projects.
element
required · object
Show child attributes
JSON
{ "element": { "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53", "codename": "object_codename", "external_id": "your-own-custom-identifier" }, "value": "... <h3>Medium roast</h3>\n<p>These exempt a <strong>stronger</strong> flavor than light <a data-item-id=\"f4b3fc05-e988-4dae-9ac1-a94aba566474\">roasts</a>. The beans are still more matte than oily<sup><a href=\"#footnote-1\">1</a></sup>.</p>\n<figure data-asset-id=\"66d73245-10e5-4478-93e7-5609fee3cdf7\"><img src=\"#\" data-asset-id=\"66d73245-10e5-4478-93e7-5609fee3cdf7\"></figure>\n<p>Caffeine contents are decreased. Medium roasts lack the <code>grainy</code> taste of lighter roasts. You also get a more balanced flavor, aroma and acidity.</p>\n<object type=\"application/kenticocloud\" data-type=\"component\" data-id=\"382abced-bfb6-4ee9-a2d4-2c3b8cd8ba5d\"></object>\n ...", "components": [ { "id": "382abced-bfb6-4ee9-a2d4-2c3b8cd8ba5d", "type": { "id": "f4cb13df-d61d-572e-8f3b-3afe7e3a7ea1" }, "elements": [ { "element": { "id": "0b9173d6-1c94-5fb0-a010-86eef9013fd4" }, "value": "<p>Component on level 2</p>\n<object type=\"application/kenticocloud\" data-type=\"component\" data-id=\"7c1ca8b2-2fa8-41d8-be02-bf157d3fa225\"></object>", "components": [ { "id": "7c1ca8b2-2fa8-41d8-be02-bf157d3fa225", "type": { "id": "37684e4c-9303-589b-a937-c7c165171b38" }, "elements": [ { "element": { "id": "ff50c0e0-226e-5474-b71b-2af194edd7c4" }, "value": "<p>Nested component on level 3</p>", "components": [] } ] } ] }, { "element": { "id": "edd22f22-ccd6-56e6-9fe2-676a7e250d8c" }, "value": [ { "id": "f206b928-7609-5192-bd31-6eb6aae48096" } ] } ] } ]}
value[]
required · array · unique items
id
string · uuid
codename
string · write-only
The renditions property is optional, but once you specify a rendition for the asset, you need to specify the renditions for all the other referenced assets in the element as well. This is due to the backward compatibility of the API.
external_id
string · write-only
renditions[]
array · max. 1 items
Show child attributes
The component's ID. Must match the data-id of the component object inside the value of the rich text element.
The referenced object's codename. The value of the codename property must meet the conditions defined in rules for codenames.
The referenced object’s external ID. The value of the external_id property must not contain the following characters: /, ., ;.
The component's elements based on the specified content type.
Reference to a specific object in the environment.
The value of asset elements is an array of Reference objects, each representing a single asset. Every asset can be referenced only once. You can also reference the asset's renditions by the renditions property. Renditions are specific to images only.When retrieving asset elements, the Management API will always reference assets with their internal IDs. When updating asset elements via the API, you can reference an asset by its internal ID or external ID. Also, you can reference a rendition by its internal ID or external ID.
The referenced object's codename. The value of the codename property must meet the conditions defined in rules for codenames.
The referenced object’s external ID. The value of the external_id property must not contain the following characters: /, ., ;.
The asset's renditions. Renditions are different editions of the original image used in Kontent.When you update a rendition via the API, it gets changed across all assets using this rendition. But when you do the same in the UI, for example, by duplicating an item that contains a rendition, changes to the rendition are not applied across the items.To remove a rendition, leave the array empty.
The API uses internal IDs for referencing objects. This means that the reference objects in the API responses will always use internal IDs.
Nesting HTML elements in rich textAt the top level, only the following elements are allowed: <p>, <h1>, <h2>, <h3>, <h4>, <h5>, <h6>, <ul>, <ol>, <table>, <object> (for content items and components), and <figure> (for images). These top-level elements can NOT be nested except for lists (<ul> and
The components can be nested up to 6 levels deep.
<ol>
). Text is not allowed at the top level with the exception of new lines and white space characters.
The table <td> element can alternatively contain top level elements except for <table> and <object>.
The <p>, <h1>, <h2>, <h3>, <h4>, <h5>, <h6>, <li>, and <td> elements can contain text and the following inline elements: <a>, <code>, <em>, <strong>, <sub>, <sup>. These elements can also contain
The <a>, <code>, <em>, and <strong> inline elements can be nested but they cannot cross one another. For example, it's not allowed to open the <em> element, then the <strong> element, and then close the <em> element. Lists can be nested as long as the nested list (<ul> or <ol>) is the last HTML element of the list item, for example, <ol><li>List item<ul><li>Nested list item</li></ul></li></ol>.
The API uses internal IDs for referencing objects. This means that the reference objects in the API responses will always use internal IDs.
The renditions property is optional, but once you specify a rendition for the asset, you need to specify the renditions for all the other referenced assets in the element as well. This is due to the backward compatibility of the API.
and the custom elements overview