Elements in variants and assets

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.

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.

Asset element

element

required · object

Reference to a specific object in the environment.

The API uses internal IDs for referencing objects. This means that the reference objects in the API responses will always use internal IDs.

Show child attributes

value[]

required · array · unique items

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.

Reference to an asset

id

string · uuid

The referenced object's internal ID.

codename

string · write-only

The referenced object's codename. The value of the codename property must meet the conditions defined in rules for codenames.

external_id

string · write-only

The referenced object’s external ID. The value of the external_id property must not contain the following characters: /, ., ;.

renditions[]

array · max. 1 items

The asset's renditions. Renditions are different editions of the original image used in Kontent.

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.

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.

Show child attributes

JSON

{
  "element": {
    "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53",
    "codename": "object_codename",
    "external_id": "your-own-custom-identifier"
  },
  "value": []
}

Custom element

Create your own custom element , or see the integrations topic on GitHub

and the custom elements overview

to find custom elements you can use or customize for your scenario.

element

required · object

Reference to a specific object in the environment.

The API uses internal IDs for referencing objects. This means that the reference objects in the API responses will always use internal IDs.

Show child attributes

value

required · string · nullable · max. 200000 chars

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.

searchable_value

string · nullable · max. 200000 chars

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.

JSON

{
  "element": {
    "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53",
    "codename": "object_codename",
    "external_id": "your-own-custom-identifier"
  },
  "value": "#00ffff",
  "searchable_value": "#00ffff #0ff Cyan Aqua"
}

Date & time element

element

required · object

Reference to a specific object in the environment.

The API uses internal IDs for referencing objects. This means that the reference objects in the API responses will always use internal IDs.

Show child attributes

value

required · string · nullable · date-time

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.

display_timezone

string · nullable

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".

Default value:

null

JSON

{
  "element": {
    "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53",
    "codename": "object_codename",
    "external_id": "your-own-custom-identifier"
  },
  "value": "2017-10-31T00:00:00Z",
  "display_timezone": "Europe/London"
}

Linked items element

element

required · object

Reference to a specific object in the environment.

The API uses internal IDs for referencing objects. This means that the reference objects in the API responses will always use internal IDs.

Show child attributes

value[]

required · array

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.

Show child attributes

JSON

{
  "element": {
    "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53",
    "codename": "object_codename",
    "external_id": "your-own-custom-identifier"
  },
  "value": {
    "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53",
    "codename": "object_codename",
    "external_id": "your-own-custom-identifier"
  }
}

Multiple choice element

element

required · object

Reference to a specific object in the environment.

The API uses internal IDs for referencing objects. This means that the reference objects in the API responses will always use internal IDs.

Show child attributes

value[]

required · array · unique items

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.

Show child attributes

JSON

{
  "element": {
    "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53",
    "codename": "object_codename",
    "external_id": "your-own-custom-identifier"
  },
  "value": {
    "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53",
    "codename": "object_codename",
    "external_id": "your-own-custom-identifier"
  }
}

Number element

element

required · object

Reference to a specific object in the environment.

The API uses internal IDs for referencing objects. This means that the reference objects in the API responses will always use internal IDs.

Show child attributes

value

required · number · nullable · Floating-point number

When retrieving and updating Number elements, the format of the value will be identical for both GET and PUT operations.

JSON

{
  "element": {
    "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53",
    "codename": "object_codename",
    "external_id": "your-own-custom-identifier"
  },
  "value": 3.14159
}

Rich text overview

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.

Rich text element

element

required · object

Reference to a specific object in the environment.

The API uses internal IDs for referencing objects. This means that the reference objects in the API responses will always use internal IDs.

Show child attributes

value

required · string · max. 100000 chars

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.

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 <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 <br/> elements for specifying line breaks. 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>.

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.

components[]

array · unique items

A list of components used in the rich text's value.

The components can be nested up to 6 levels deep.

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"
            }
          ]
        }
      ]
    }
  ]
}

HTML5 elements allowed in rich text

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.

Top-level elements

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>.

Types	HTML elements	Notes
Paragraphs	`<p>...</p>`	Can contain text with inline formatting elements.
Headings	`<h1>...</h1>`, `<h2>...</h2>`, `<h3>...</h3>`, `<h4>...</h4>`, `<h5>...</h5>`, `<h6>...</h6>`	Can contain text with inline formatting elements.
Lists	`<ol><li>...</li></ol>`, `<ul><li>...</li></ul>`	Individual list items `<li>` can contain text with inline formatting elements.
Assets	`<figure ...><img ...></figure>`
Tables	`<table><tbody><tr><td>...</td></tr></tbody></table>`	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	`<object ...></object>`	Content items and components are not supported inside table cells.

Elements for inline text formatting

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>`	Superscript and subscript are mutually exclusive.
Subscript	`<sub>...</sub>`	Superscript and subscript are mutually exclusive.
Code	`<code>...</code>`
Links	`<a ...>...</a>`	For the list of supported `<a>` attributes, see Links in rich text.
Line breaks	`<br/>`

Assets in rich text

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 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.

JSON

{
...
  "element": {
    "codename": "asset_referenced_by_internal_id"
  },
  "value": "<figure data-asset-id=\"512047f1-2f7f-45fd-9e90-e71b8feae017\"><img src=\"#\" data-asset-id=\"512047f1-2f7f-45fd-9e90-e71b8feae017\"></figure>"
...
  "element": {
    "codename": "asset_referenced_by_external_id"
  },
  "value": "<figure data-asset-external-id=\"coffee_beans\"></figure>"
...
 "element": {
   "codename": "asset_referenced_by_codename"
      },
  "value": "<figure data-asset-codename=\"coffee_asset\"><img src=\"#\" data-asset-codename=\"coffee_asset\"></figure>"
...
}

Components in rich text

Component object

id

required · string · uuid

The component's ID. Must match the data-id of the component object inside the value of the rich text element.

type

required · nestedSchema

Reference to the component's content type.

id

string · uuid

The referenced object's internal ID.

codename

string · write-only

The referenced object's codename. The value of the codename property must meet the conditions defined in rules for codenames.

external_id

string · write-only

The referenced object’s external ID. The value of the external_id property must not contain the following characters: /, ., ;.

elements[]

required · array · unique items

The component's elements based on the specified content type.

Any of:

Asset element

Custom element

Date & time element

Linked items element

Multiple choice element

Number element

Rich text element

Taxonomy element

Text element

URL slug element

Asset element

element

required · object

Reference to a specific object in the environment.

The API uses internal IDs for referencing objects. This means that the reference objects in the API responses will always use internal IDs.

Show child attributes

value[]

required · array · unique items

Reference to an asset

id

string · uuid

The referenced object's internal ID.

codename

string · write-only

The referenced object's codename. The value of the codename property must meet the conditions defined in rules for codenames.

external_id

string · write-only

The referenced object’s external ID. The value of the external_id property must not contain the following characters: /, ., ;.

renditions[]

array · max. 1 items

The asset's renditions. Renditions are different editions of the original image used in Kontent.

Show child attributes

JSON

{
  "id": "382abced-bfb6-4ee9-a2d4-2c3b8cd8ba5d",
  "type": {
    "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53",
    "codename": "object_codename",
    "external_id": "your-own-custom-identifier"
  },
  "elements": []
}

Components in rich text are defined by the <object> block element. The <object> element requires the type, data-type, and data-id attributes.

JSON

{
...
  "element": {
    "codename": "component_referenced_by_internal_id"
  },
  "value": "<object type=\"application/kenticocloud\" data-type=\"component\" data-id=\"382abced-bfb6-4ee9-a2d4-2c3b8cd8ba5d\"></object>"
...
}

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.

Nesting of components

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.

JSON

{
  "element": {
    "id": "49150275-064b-5314-be6e-b93e1d7661e1"
  },
  "value": "<p>Level 1: Content in a rich text element</p>\n<object type=\"application/kenticocloud\" data-type=\"component\" data-id=\"382abced-bfb6-4ee9-a2d4-2c3b8cd8ba5d\"></object>",
  "components": [
    {
      "id": "382abced-bfb6-4ee9-a2d4-2c3b8cd8ba5d",
      "type": {
        "id": "f4cb13df-d61d-572e-8f3b-3afe7e3a7ea1"
      },
      "elements": [
        {
          "element": {
            "id": "0b9173d6-1c94-5fb0-a010-86eef9013fd4"
          },
          "value": "<p>Level 2: content in a nested component</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>Level 3: content in a nested component</p>",
                  "components": []
                }
              ]
            }
          ]
        },
        {
          "element": {
            "id": "edd22f22-ccd6-56e6-9fe2-676a7e250d8c"
          },
          "value": [
            {
              "id": "f206b928-7609-5192-bd31-6eb6aae48096"
            }
          ]
        }
      ]
    }
  ]
}

Content items in rich text

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.

JSON

{
...
  "element": {
    "codename": "item_referenced_by_internal_id"
  },
  "value": "<object type=\"application/kenticocloud\" data-type=\"item\" data-id=\"f4b3fc05-e988-4dae-9ac1-a94aba566474\"></object>"
...
  "element": {
    "codename": "item_referenced_by_external_id"
  },
  "value": "<object type=\"application/kenticocloud\" data-type=\"item\" data-external-id=\"59713\"></object>"
...
  "element": {
        "codename": "item_referenced_by_codename"
      },
  "value": "<object type=\"application/kenticocloud\" data-type=\"item\" data-codename=\"coffee_item\"></object>"
...
}

Links in rich text

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

Links to URLs require the href attribute.

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 → ftp://example.com (no change)
example.com → http://example.com
about-us.html → http://about-us.html
/about-us.html → /about-us.html (no change)
?query → ?query (no change)
#anchor → #anchor (no change)
javascript:alert() → http://javascript:alert()
javascript://%0aalert() → http://javascript://%0aalert()
data:text/html,<script>alert()</script>→ http://data:text/html,<script>alert()</script>

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.

Other <a> attributes, such as target and rel, are not supported for URL links.

JSON

{
...
  "element": {
    "codename": "link_to_url"
  },
  "value": "<p><a href=\"https://example.com\">example link</a></p>"
...
  "element": {
    "codename": "link_to_url_new_window"
  },
  "value": "<p><a href=\"https://example.com\" data-new-window=\"true\">example link</a></p>"
...
  "element": {
    "codename": "link_to_url_with_title"
  },
  "value": "<p><a href=\"https://example.com\" title=\"Example\">example link</a></p>"
...
}

Links to email addresses

Email links require the data-email-address attribute. Optionally, the link can contain the data-email-subject attribute.

JSON

{
...
  "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>"
...
}

Links to phone numbers

Phone links require the data-phone-number attribute.

JSON

{
...
  "element": {
    "codename": "link_to_phone_number"
  },
  "value": "<p><a data-phone-number=\"+31-682144594\">+31-682144594</a></p>"
...
}

Links to assets

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.

JSON

{
...
  "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>"
...
}

Links to content items

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 content t.

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>"
...
}

Lists in rich text

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.

JSON

{
...
  "value": "<ol><li>A list item</li><li>Another list item<ul><li>Nested list item</li></ul></li></ol>"
...
}

Tables in rich text

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.

JSON

{
...
  "value": "<table><tbody><tr><td>Type A</td><td>Type B</td><td>Type C</td></tr>   <tr>   <td>12.4</td><td>3.14</td><td>34.1</td></tr></tbody></table>"
...
}

Subpages element

The Subpages element requires Web Spotlight and live preview.

element

required · object

Reference to a specific object in the environment.

The API uses internal IDs for referencing objects. This means that the reference objects in the API responses will always use internal IDs.

Show child attributes

value[]

required · array

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.

Show child attributes

JSON

{
  "element": {
    "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53",
    "codename": "object_codename",
    "external_id": "your-own-custom-identifier"
  },
  "value": {
    "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53",
    "codename": "object_codename",
    "external_id": "your-own-custom-identifier"
  }
}

Taxonomy element

element

required · object

Reference to a specific object in the environment.

The API uses internal IDs for referencing objects. This means that the reference objects in the API responses will always use internal IDs.

Show child attributes

value[]

required · array · unique items

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.

Show child attributes

JSON

{
  "element": {
    "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53",
    "codename": "object_codename",
    "external_id": "your-own-custom-identifier"
  },
  "value": {
    "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53",
    "codename": "object_codename",
    "external_id": "your-own-custom-identifier"
  }
}

Text element

element

required · object

Reference to a specific object in the environment.

The API uses internal IDs for referencing objects. This means that the reference objects in the API responses will always use internal IDs.

Show child attributes

value

required · string · nullable · max. 100000 chars

When retrieving and updating text elements, the format of the value property will be identical for both GET and PUT operations.

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.

JSON

{
  "element": {
    "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53",
    "codename": "object_codename",
    "external_id": "your-own-custom-identifier"
  },
  "value": "Plaintext, plain and simple."
}

URL slug element

element

required · object

Reference to a specific object in the environment.

The API uses internal IDs for referencing objects. This means that the reference objects in the API responses will always use internal IDs.

Show child attributes

mode

required · string

Determines the element's mode of operation.

You can change the text element the URL slug depends on either in the UI or via the API.

value

string

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.

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.

JSON

{
  "element": {
    "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53",
    "codename": "object_codename",
    "external_id": "your-own-custom-identifier"
  },
  "mode": "autogenerated",
  "value": "user-and-seo-friendly-url-slug"
}

Elements in variants and assets

Asset element

element

required · object

Reference to a specific object in the environment.

The API uses internal IDs for referencing objects. This means that the reference objects in the API responses will always use internal IDs.

Show child attributes

value[]

required · array · unique items

Reference to an asset

id

string · uuid

The referenced object's internal ID.

codename

string · write-only

The referenced object's codename. The value of the codename property must meet the conditions defined in rules for codenames.

external_id

string · write-only

The referenced object’s external ID. The value of the external_id property must not contain the following characters: /, ., ;.

renditions[]

array · max. 1 items

The asset's renditions. Renditions are different editions of the original image used in Kontent.

Show child attributes

JSON

{
  "element": {
    "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53",
    "codename": "object_codename",
    "external_id": "your-own-custom-identifier"
  },
  "value": []
}

Custom element

Create your own custom element , or see the integrations topic on GitHub

and the custom elements overview

to find custom elements you can use or customize for your scenario.

element

required · object

Reference to a specific object in the environment.

The API uses internal IDs for referencing objects. This means that the reference objects in the API responses will always use internal IDs.

Show child attributes

value

required · string · nullable · max. 200000 chars

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.

searchable_value

string · nullable · max. 200000 chars

JSON

{
  "element": {
    "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53",
    "codename": "object_codename",
    "external_id": "your-own-custom-identifier"
  },
  "value": "#00ffff",
  "searchable_value": "#00ffff #0ff Cyan Aqua"
}

Date & time element

element

required · object

Reference to a specific object in the environment.

The API uses internal IDs for referencing objects. This means that the reference objects in the API responses will always use internal IDs.

Show child attributes

value

required · string · nullable · date-time

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.

display_timezone

string · nullable

Default value:

null

JSON

{
  "element": {
    "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53",
    "codename": "object_codename",
    "external_id": "your-own-custom-identifier"
  },
  "value": "2017-10-31T00:00:00Z",
  "display_timezone": "Europe/London"
}

Linked items element

element

required · object

Reference to a specific object in the environment.

The API uses internal IDs for referencing objects. This means that the reference objects in the API responses will always use internal IDs.

Show child attributes

value[]

required · array

Show child attributes

JSON

{
  "element": {
    "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53",
    "codename": "object_codename",
    "external_id": "your-own-custom-identifier"
  },
  "value": {
    "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53",
    "codename": "object_codename",
    "external_id": "your-own-custom-identifier"
  }
}

Multiple choice element

element

required · object

Reference to a specific object in the environment.

The API uses internal IDs for referencing objects. This means that the reference objects in the API responses will always use internal IDs.

Show child attributes

value[]

required · array · unique items

Show child attributes

JSON

{
  "element": {
    "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53",
    "codename": "object_codename",
    "external_id": "your-own-custom-identifier"
  },
  "value": {
    "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53",
    "codename": "object_codename",
    "external_id": "your-own-custom-identifier"
  }
}

Number element

element

required · object

Reference to a specific object in the environment.

The API uses internal IDs for referencing objects. This means that the reference objects in the API responses will always use internal IDs.

Show child attributes

value

required · number · nullable · Floating-point number

When retrieving and updating Number elements, the format of the value will be identical for both GET and PUT operations.

JSON

{
  "element": {
    "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53",
    "codename": "object_codename",
    "external_id": "your-own-custom-identifier"
  },
  "value": 3.14159
}

Rich text overview

Rich text element

element

required · object

Reference to a specific object in the environment.

The API uses internal IDs for referencing objects. This means that the reference objects in the API responses will always use internal IDs.

Show child attributes

value

required · string · max. 100000 chars

components[]

array · unique items

A list of components used in the rich text's value.

The components can be nested up to 6 levels deep.

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"
            }
          ]
        }
      ]
    }
  ]
}

HTML5 elements allowed in rich text

Top-level elements

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>.

Types	HTML elements	Notes
Paragraphs	`<p>...</p>`	Can contain text with inline formatting elements.
Headings	`<h1>...</h1>`, `<h2>...</h2>`, `<h3>...</h3>`, `<h4>...</h4>`, `<h5>...</h5>`, `<h6>...</h6>`	Can contain text with inline formatting elements.
Lists	`<ol><li>...</li></ol>`, `<ul><li>...</li></ul>`	Individual list items `<li>` can contain text with inline formatting elements.
Assets	`<figure ...><img ...></figure>`
Tables	`<table><tbody><tr><td>...</td></tr></tbody></table>`	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	`<object ...></object>`	Content items and components are not supported inside table cells.

Elements for inline text formatting

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>`	Superscript and subscript are mutually exclusive.
Subscript	`<sub>...</sub>`	Superscript and subscript are mutually exclusive.
Code	`<code>...</code>`
Links	`<a ...>...</a>`	For the list of supported `<a>` attributes, see Links in rich text.
Line breaks	`<br/>`

Assets in rich text

JSON

{
...
  "element": {
    "codename": "asset_referenced_by_internal_id"
  },
  "value": "<figure data-asset-id=\"512047f1-2f7f-45fd-9e90-e71b8feae017\"><img src=\"#\" data-asset-id=\"512047f1-2f7f-45fd-9e90-e71b8feae017\"></figure>"
...
  "element": {
    "codename": "asset_referenced_by_external_id"
  },
  "value": "<figure data-asset-external-id=\"coffee_beans\"></figure>"
...
 "element": {
   "codename": "asset_referenced_by_codename"
      },
  "value": "<figure data-asset-codename=\"coffee_asset\"><img src=\"#\" data-asset-codename=\"coffee_asset\"></figure>"
...
}

Components in rich text

Component object

id

required · string · uuid

The component's ID. Must match the data-id of the component object inside the value of the rich text element.

type

required · nestedSchema

Reference to the component's content type.

id

string · uuid

The referenced object's internal ID.

codename

string · write-only

The referenced object's codename. The value of the codename property must meet the conditions defined in rules for codenames.

external_id

string · write-only

The referenced object’s external ID. The value of the external_id property must not contain the following characters: /, ., ;.

elements[]

required · array · unique items

The component's elements based on the specified content type.

Any of:

Asset element

Custom element

Date & time element

Linked items element

Multiple choice element

Number element

Rich text element

Taxonomy element

Text element

URL slug element

Asset element

element

required · object

Reference to a specific object in the environment.

The API uses internal IDs for referencing objects. This means that the reference objects in the API responses will always use internal IDs.

Show child attributes

value[]

required · array · unique items

Reference to an asset

id

string · uuid

The referenced object's internal ID.

codename

string · write-only

The referenced object's codename. The value of the codename property must meet the conditions defined in rules for codenames.

external_id

string · write-only

The referenced object’s external ID. The value of the external_id property must not contain the following characters: /, ., ;.

renditions[]

array · max. 1 items

The asset's renditions. Renditions are different editions of the original image used in Kontent.

Show child attributes

JSON

{
  "id": "382abced-bfb6-4ee9-a2d4-2c3b8cd8ba5d",
  "type": {
    "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53",
    "codename": "object_codename",
    "external_id": "your-own-custom-identifier"
  },
  "elements": []
}

Components in rich text are defined by the <object> block element. The <object> element requires the type, data-type, and data-id attributes.

JSON

{
...
  "element": {
    "codename": "component_referenced_by_internal_id"
  },
  "value": "<object type=\"application/kenticocloud\" data-type=\"component\" data-id=\"382abced-bfb6-4ee9-a2d4-2c3b8cd8ba5d\"></object>"
...
}

Nesting of components

JSON

{
  "element": {
    "id": "49150275-064b-5314-be6e-b93e1d7661e1"
  },
  "value": "<p>Level 1: Content in a rich text element</p>\n<object type=\"application/kenticocloud\" data-type=\"component\" data-id=\"382abced-bfb6-4ee9-a2d4-2c3b8cd8ba5d\"></object>",
  "components": [
    {
      "id": "382abced-bfb6-4ee9-a2d4-2c3b8cd8ba5d",
      "type": {
        "id": "f4cb13df-d61d-572e-8f3b-3afe7e3a7ea1"
      },
      "elements": [
        {
          "element": {
            "id": "0b9173d6-1c94-5fb0-a010-86eef9013fd4"
          },
          "value": "<p>Level 2: content in a nested component</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>Level 3: content in a nested component</p>",
                  "components": []
                }
              ]
            }
          ]
        },
        {
          "element": {
            "id": "edd22f22-ccd6-56e6-9fe2-676a7e250d8c"
          },
          "value": [
            {
              "id": "f206b928-7609-5192-bd31-6eb6aae48096"
            }
          ]
        }
      ]
    }
  ]
}

Content items in rich text

JSON

{
...
  "element": {
    "codename": "item_referenced_by_internal_id"
  },
  "value": "<object type=\"application/kenticocloud\" data-type=\"item\" data-id=\"f4b3fc05-e988-4dae-9ac1-a94aba566474\"></object>"
...
  "element": {
    "codename": "item_referenced_by_external_id"
  },
  "value": "<object type=\"application/kenticocloud\" data-type=\"item\" data-external-id=\"59713\"></object>"
...
  "element": {
        "codename": "item_referenced_by_codename"
      },
  "value": "<object type=\"application/kenticocloud\" data-type=\"item\" data-codename=\"coffee_item\"></object>"
...
}

Links in rich text

Links to URLs

Links to URLs require the href attribute.

http://example.com → http://example.com (no change)
https://example.com → https://example.com (no change)
ftp://example.com → ftp://example.com (no change)
example.com → http://example.com
about-us.html → http://about-us.html
/about-us.html → /about-us.html (no change)
?query → ?query (no change)
#anchor → #anchor (no change)
javascript:alert() → http://javascript:alert()
javascript://%0aalert() → http://javascript://%0aalert()
data:text/html,<script>alert()</script>→ http://data:text/html,<script>alert()</script>

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.

Other <a> attributes, such as target and rel, are not supported for URL links.

JSON

{
...
  "element": {
    "codename": "link_to_url"
  },
  "value": "<p><a href=\"https://example.com\">example link</a></p>"
...
  "element": {
    "codename": "link_to_url_new_window"
  },
  "value": "<p><a href=\"https://example.com\" data-new-window=\"true\">example link</a></p>"
...
  "element": {
    "codename": "link_to_url_with_title"
  },
  "value": "<p><a href=\"https://example.com\" title=\"Example\">example link</a></p>"
...
}

Links to email addresses

Email links require the data-email-address attribute. Optionally, the link can contain the data-email-subject attribute.

JSON

{
...
  "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>"
...
}

Links to phone numbers

Phone links require the data-phone-number attribute.

JSON

{
...
  "element": {
    "codename": "link_to_phone_number"
  },
  "value": "<p><a data-phone-number=\"+31-682144594\">+31-682144594</a></p>"
...
}

Links to assets

JSON

{
...
  "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>"
...
}

Links to content items

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>"
...
}

Lists in rich text

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.

JSON

{
...
  "value": "<ol><li>A list item</li><li>Another list item<ul><li>Nested list item</li></ul></li></ol>"
...
}

Tables in rich text

JSON

{
...
  "value": "<table><tbody><tr><td>Type A</td><td>Type B</td><td>Type C</td></tr>   <tr>   <td>12.4</td><td>3.14</td><td>34.1</td></tr></tbody></table>"
...
}

Subpages element

The Subpages element requires Web Spotlight and live preview.

element

required · object

Reference to a specific object in the environment.

The API uses internal IDs for referencing objects. This means that the reference objects in the API responses will always use internal IDs.

Show child attributes

value[]

required · array

Show child attributes

JSON

{
  "element": {
    "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53",
    "codename": "object_codename",
    "external_id": "your-own-custom-identifier"
  },
  "value": {
    "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53",
    "codename": "object_codename",
    "external_id": "your-own-custom-identifier"
  }
}

Taxonomy element

element

required · object

Reference to a specific object in the environment.

The API uses internal IDs for referencing objects. This means that the reference objects in the API responses will always use internal IDs.

Show child attributes

value[]

required · array · unique items

Show child attributes

JSON

{
  "element": {
    "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53",
    "codename": "object_codename",
    "external_id": "your-own-custom-identifier"
  },
  "value": {
    "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53",
    "codename": "object_codename",
    "external_id": "your-own-custom-identifier"
  }
}

Text element

element

required · object

Reference to a specific object in the environment.

The API uses internal IDs for referencing objects. This means that the reference objects in the API responses will always use internal IDs.

Show child attributes

value

required · string · nullable · max. 100000 chars

When retrieving and updating text elements, the format of the value property will be identical for both GET and PUT operations.

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.

JSON

{
  "element": {
    "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53",
    "codename": "object_codename",
    "external_id": "your-own-custom-identifier"
  },
  "value": "Plaintext, plain and simple."
}

URL slug element

element

required · object

Reference to a specific object in the environment.

The API uses internal IDs for referencing objects. This means that the reference objects in the API responses will always use internal IDs.

Show child attributes

mode

required · string

Determines the element's mode of operation.

You can change the text element the URL slug depends on either in the UI or via the API.

value

string

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.

JSON

{
  "element": {
    "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53",
    "codename": "object_codename",
    "external_id": "your-own-custom-identifier"
  },
  "mode": "autogenerated",
  "value": "user-and-seo-friendly-url-slug"
}