---
title: Headless content
related:
  - https://docs.kentico.com/documentation/developers-and-admins/configuration/headless-channel-management.md
  - https://docs.kentico.com/documentation/developers-and-admins/development/content-retrieval/retrieve-headless-content.md
---

> Agent instructions:
> **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown.
>
> - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version.
> - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt).

> **License:** Advanced license required.
>
> Features described on this page require the Xperience by Kentico **Advanced** license tier.

Headless content items store content that is intended for distribution to channels outside of the system through a headless API ([GraphQL](https://graphql.org/)). This way, you can consolidate your various channels, like mobile apps, web apps, kiosks, etc. into the Xperience ecosystem. When modeling headless content, one headless item usually represents one unit of the presentation layer (page, screen, navigation, etc.) in the channel to which you provide the data.

Headless items for each channel are managed in respective headless channel applications – by default, the name of the application corresponds to the name of the channel. The application enables you to create, delete or edit the content and properties of headless items. It also provides intuitive headless item lifecycle management.

![Headless items](https://docs.kentico.com/docsassets/documentation/headless-content/headless_items_overview.png "Headless items")

## Create headless items

To create a new headless item:

1. Open a headless channel application.
2. Select **New headless item**.

   ![New headless item](https://docs.kentico.com/docsassets/documentation/headless-content/new_headless_item.png "New headless item")
3. Enter the headless item name.
4. Select a content type from the list of available content types.

   ![New headless item - select content type](https://docs.kentico.com/docsassets/documentation/headless-content/new_headless_item_select_type.png "New headless item - select content type")
5. Select **Continue**.
6. Enter the values required by the selected content type.
   - In many cases, headless items will have fields that allow you to add content by selecting reusable content items (blocks of text, images, etc.). See [Content hub](https://docs.kentico.com/documentation/business-users/content-hub.md) to learn more. When selecting reusable content items, note that secured items with the **Requires authentication** flag enabled are not included in headless content.
7. **Save** or **Publish** the new headless item.
   - Saving creates a _Draft_ of the headless item.
   - Publishing immediately sets the headless item to the _Published_ status.
   - To save the item and immediately continue creating another item, select **Save and create another** instead of **Save**. By default, the same content type is used, but you can select a different one.

The headless item is now created. Keep in mind that only _Published_ items are available through the [headless API](https://docs.kentico.com/documentation/developers-and-admins/development/content-retrieval/retrieve-headless-content.md). If [content locking](https://docs.kentico.com/documentation/business-users/content-locking.md) is enabled, the item is now locked and only you can edit it.

## Clone headless items

Cloning a headless item allows you to create a new item with the same data. You can clone all [language variants](#translate-headless-items) of an item or just a selected one.

To clone a headless item:

1. Open a headless channel application.
2. [Find](#find-headless-items) the item you want to clone.
3. Select the **Clone** () action.

   ![Clone action](https://docs.kentico.com/docsassets/documentation/headless-content/headless_item_clone.png "Clone action")
4. Enter the new headless item name. This name will be used for all language variants.
   - The default name is _(Clone) {original name}_.
5. If you want to clone only the current language variant of the item, clear the **Clone all language variants** checkbox. By default, all language variants are cloned.
6. Select **Clone**.

The new item is created in the _Draft_ step, where you can [edit](#edit-headless-items) it. The item needs to be [published](#publish-headless-items) to be available through the headless API.

Each language variant needs to be published separately. Use the language switcher to access other language variants of the new item.

![Language switcher](https://docs.kentico.com/docsassets/documentation/headless-content/clone_language_switcher.png "Language switcher")

If [Content locking](https://docs.kentico.com/documentation/business-users/content-locking.md) is enabled, the new item is not locked immediately after cloning. You only acquire the lock once you start editing.

## Find headless items

A headless channel application may contain a large number of headless items. The search bar allows you to find headless items with a name or content type matching the entered text.

You can also **Filter** the list of headless items to display only selected content types, items with specific statuses, or items containing specific tags.

![Headless items filter](https://docs.kentico.com/docsassets/documentation/headless-content/headless_items_filter.png "Headless items filter")

## Edit headless items

To edit a headless item:

1. Open a headless channel application.
2. Select the headless item you want to edit.
   - Use the search bar or filter to [find headless items](#find-headless-items).
   - If you have [multiple languages](https://docs.kentico.com/documentation/developers-and-admins/configuration/languages.md) set up, select the language in which you want to edit the headless item from the language switcher.
3. Make sure the headless item is in the _Draft_ status or another [custom workflow step](https://docs.kentico.com/documentation/developers-and-admins/configuration/workflows.md).
   - When a headless item is _Published_, select **Edit item** to move the headless item to the _Draft_ step.

     ![Edit headless item](https://docs.kentico.com/docsassets/documentation/headless-content/headless_item_edit_button.png "Edit headless item")
   - When a headless item is _Unpublished_, select **Create new version** to move the headless item to the _Draft_ step.

     ![Create a new version of the headless item](https://docs.kentico.com/docsassets/documentation/headless-content/headless_item_create_new_version_button.png "Create a new version of the headless item")
4. Edit the fields of the headless item.
   - If [content locking](https://docs.kentico.com/documentation/business-users/content-locking.md) is enabled, the item has been automatically locked when you started editing. Only you can edit until the [lock is released](https://docs.kentico.com/documentation/business-users/content-locking.md#release-a-content-lock).
5. **Save** the changes.

The headless item is now edited.

> **Info:** **Overwrite protection**
>
> The system has a basic overwrite protection even when [content locking](https://docs.kentico.com/documentation/business-users/content-locking.md) is not enabled. When you and another user are both editing the same item and the other user saves their changes first, the system prevents you from saving your changes. Reopen the item in a new tab to load the latest version, apply your changes, and save.

## Preview headless items

As headless content can have different presentations on multiple platforms, it is not possible to include a preview of headless items directly within Xperience. To see how your content will appear on a specific platform, you need to preview the content directly in the target environment.

You can use the **Preview button** to quickly get to your preview environment. The button links to a single URL, as it is not currently possible to assign a specific URL for each headless item separately.

However, before you can make use of the Preview button, you need to ask your administrators to set up a **[Preview URL](https://docs.kentico.com/documentation/developers-and-admins/configuration/headless-channel-management.md)** in the channel settings. The button is present only once the Preview URL is set up.

## Revert changes made to a headless item

After creating a new version of a headless item, the item goes through a new editing cycle with the _Draft_ step and optionally other [custom workflow steps](https://docs.kentico.com/documentation/developers-and-admins/configuration/workflows.md).

At any time before the new version is published, you can revert the item back to the last _Published_ status. All changes made in any workflow step will be lost.

1. Open a headless channel application.
2. Select the headless item whose changes you want to revert.
   - Use the search bar or filter to [find headless items](#find-headless-items).
3. Expand the **Publish** or **Change workflow step** menu.
4. Select **Revert to published** to revert the changes.

![Reverting a headless item to its published status](https://docs.kentico.com/docsassets/documentation/headless-content/headless_item_revert_to_published.png "Reverting a headless item to its published status")

The headless item is now reverted to its _Published_ status. If [content locking](https://docs.kentico.com/documentation/business-users/content-locking.md) is enabled, this action releases the content lock.

## Publish headless items

Headless items can be published under the following conditions:

- If the headless item's content type is under [workflow](https://docs.kentico.com/documentation/developers-and-admins/configuration/workflows.md), the item must be in the last step of the workflow, or you need to belong to a role with full control for the given workflow (this allows you to publish items from any step).
- For headless items that are not under workflow, the item must be in the _Draft_ step.
- If [content locking](https://docs.kentico.com/documentation/business-users/content-locking.md) is enabled, the item cannot be locked by another user.

In order to publish a headless item:

1. Open a headless channel application.
2. Select the headless item you want to publish.
   - Use the search bar or filter to [find headless items](#find-headless-items).
3. Make sure the headless item has the _Draft_ status, or is in a [workflow step](https://docs.kentico.com/documentation/developers-and-admins/configuration/workflows.md) from which you are allowed to publish the item.
   - When a headless item is _Unpublished_, select **Create new version** to move the headless item to the _Draft_ step.

     ![Create a new version of the headless item](https://docs.kentico.com/docsassets/documentation/headless-content/headless_item_create_new_version_button.png "Create a new version of the headless item")
4. **Publish** the headless item. For items under workflow, select **Change workflow step** and choose the **Publish** step.
   - If the headless item has fields linking to reusable content items or pages, the cascade publishing dialog opens. You can view all linked items that are currently not _Published_. Select any of the listed items to publish them together with the headless item. To learn more about cascade publishing, see [Work with content items](https://docs.kentico.com/documentation/business-users/content-hub/content-items.md#cascade-publishing).

     > **Note:** Cascade publishing for headless items linked through fields using the _Headless item selector_ component is not supported.

The headless item is now _Published_ and available through the headless API. If [content locking](https://docs.kentico.com/documentation/business-users/content-locking.md) is enabled, publishing the item releases the content lock.

## Translate headless items

Before you can translate individual headless items in your project into other languages, you need to set those up in the **Languages** application. For detailed info on how to configure multiple languages in Xperience, see [Languages](https://docs.kentico.com/documentation/developers-and-admins/configuration/languages.md).

Afterward, you can start to translate and create language variants of your items:

1. Open a headless channel application.
2. In the header bar, open the language switcher.

   ![Language switcher in header bar](https://docs.kentico.com/docsassets/documentation/headless-content/headless_header_bar_language_switcher.png "Language switcher in header bar")

   > **Info:** The language switcher is available only if two or more languages are set up.
3. Select the language to translate headless items into.
4. Select the headless item to translate.

   - Use the search bar or filter to [find headless items](#find-headless-items).

     > **Tip:** Untranslated headless items are visually marked by the _Not translated_ () status.
5. Enter the translated name of the headless item. You can now choose one of the following options:

   - **Copy content from another language** is the preselected option. By default, the closest language in the  [fallback chain](https://docs.kentico.com/documentation/developers-and-admins/configuration/languages.md)  is preselected. You can choose a different language from the drop-down list. This option lets you prefill the headless item fields with the content available in the chosen language. If a linked item does not have a translated or published version, a warning will be displayed, and a fallback language variant of the item will be used.
   - **Create empty headless item** allows you to create an empty headless item with blank fields. Linked items need to be re-linked, and files need to be re-uploaded into the new language variant of the translated headless item.

     ![Translating headless item](https://docs.kentico.com/docsassets/documentation/headless-content/headless_item_copy_from_existing.png "Translating headless item")
6. Select **Continue**.
7. Enter the translated values of the headless item's fields.
8. **Save** the translated content item.

You have now successfully translated the headless item. Note that the new language variant is now only a _Draft_ until you [publish](#publish-headless-items) it.

If [content locking](https://docs.kentico.com/documentation/business-users/content-locking.md) is enabled, the item is now locked and only you can edit it. Variants created via _Translate using AIRA_ are locked only once you start editing.

## Unpublish headless items

Unpublished headless items are not available through the headless API, but you can still access them from the administration.

To unpublish a headless item:

1. Open a headless channel application.
2. Select a headless item you want to unpublish.
   - You can only unpublish headless items that are currently in the _Published_ status. See how to [publish headless items](#publish-headless-items).
   - Use the search bar or filter to [find headless items](#find-headless-items).
3. **Unpublish** the headless item.
4. Expand the **Edit item** menu and select **Unpublish**.

   ![Unpublishing a headless item](https://docs.kentico.com/docsassets/documentation/headless-content/headless_item_unpublish.png "Unpublishing a headless item")

The headless item is now _Unpublished_.

To edit or re-publish an unpublished headless item, use the **Create new version** action for the headless item. This creates a new version of the item in the _Draft_ step.

## Restore previous versions of headless items

See [Content versioning](https://docs.kentico.com/documentation/business-users/content-versioning.md#restore-previously-published-versions) for more information. You can restore previously published versions of headless items only when versioning is [configured](https://docs.kentico.com/documentation/developers-and-admins/configuration/content-versioning-configuration.md).

## Delete headless items

To delete a headless item:

1. Open a headless channel application.
2. Locate the headless item you want to delete.

   - Use the search bar or filter to [find headless items](#find-headless-items).
3. Select **Move to recycle bin** ().

![Delete headless items](https://docs.kentico.com/docsassets/documentation/headless-content/headless_item_delete.png "Delete headless items")

You have successfully deleted the headless item. You can find it in the recycle bin and [restore](https://docs.kentico.com/documentation/business-users/recycle-bin.md#restore-deleted-items) it later.

> **Info:** If you have translated the headless item into multiple languages, this process deletes only the current language variant of the item. In order to delete the headless item completely, you need to delete its variants in all languages. Deleting the last language variant of the headless item deletes it permanently from the system.

## Restore deleted headless items

Deleted headless items can be recovered from the recycle bin. See [Restore deleted items](https://docs.kentico.com/documentation/business-users/recycle-bin.md#restore-deleted-items) for more information.

## Headless items lifecycle

Headless items can have one of the following statuses:

-  **Draft (Initial)** – new headless items that have not been published yet.
  - Can only be accessed through the headless API when using an [API key](https://docs.kentico.com/documentation/developers-and-admins/configuration/headless-channel-management.md#manage-api-keys) with the _Headless content - Draft_ access type.
-  **Published** – headless items that are ready for use.
  - You can query published items using the headless API.
-  **Draft (New version)** – headless items that have already been published, but a new version is being edited.
  - Can only be accessed through the headless API when using an [API key](https://docs.kentico.com/documentation/developers-and-admins/configuration/headless-channel-management.md#manage-api-keys) with the _Headless content - Draft_ access type.
  - If queried with an API key using the _Headless content - Published_ access type, the previously published version is returned.
- [Custom workflow step](https://docs.kentico.com/documentation/developers-and-admins/configuration/workflows.md) (the item is being edited, "between" the _Draft_ and _Published_ status)
  - The item is accessible via the headless API as described for the _Draft_ status.
-  **Unpublished** – headless items that were previously published, but are no longer available through the headless API.
-  **Not translated** – headless items that are not yet translated into the currently selected language.
  - If [language fallbacks](https://docs.kentico.com/documentation/developers-and-admins/configuration/languages.md) are set up, the headless items are accessible through the headless API in their fallback variants.

The following diagram illustrates the default headless items lifecycle in a simplified way:

![Lifecycle transitions of headless items](https://docs.kentico.com/docsassets/documentation/headless-content/final_workflow.png "Lifecycle transitions of headless items")

## Lock and unlock headless items

When content locking is enabled, the system prevents other users from editing an item while you are making changes. See [content locking](https://docs.kentico.com/documentation/business-users/content-locking.md) for details.