content/guides/02.content/6.content-versioning.md
:video-embed{video-id="0bfed0fe-2c73-4528-8a6a-d3b39b4c0528"}
Content versioning allows teams to create and manage different versions of their content. There are several reasons to use content versioning, including drafting content without publishing it, and more ways to collaborate effectively.
::callout{icon="material-symbols:info-outline" to="/guides/content/live-preview"}
Using Versions in Live Preview
The version field is a dynamic variable can be added to the live preview URL so you can preview a specific version of an item. Check out more about live previews.
::
Navigate to Settings > Data Model, select the collection that you want to enable content versioning for, and scroll down to the content versioning section. Toggle "Enable Versions" and save your data model.
When content versioning is enabled for a collection, a global draft version is automatically available for all items. This reserved version provides a safe workspace for preparing changes before publishing to your live content.
The draft version:
::callout{icon="material-symbols:warning"}
Backward Compatibility
The reserved global "draft" version was introduced in Directus 11.16.0. If you have an existing version with the key draft and a custom name other than "Draft", the display name will be standardized to "Draft" (i.e. transformed) to support the new global versioning feature. The version content and functionality remain unchanged.
::
The Visual Editor integrates seamlessly with the draft version, allowing you to preview and edit changes in context:
Open an item within your versioned collection. At the top of the item view, you will notice a dropdown with the main Content Version displayed as "main". Select "Create Version" and provide a key and a name for the new version. You can then save your new version.
::callout{icon="material-symbols:info-outline"}
Version Source
All new versions originate from the main item. This implies that the main item acts as the single source of truth for other versions. The draft version is always available and doesn't need to be manually created.
::
Open the item in the newly created version, and make the desired edits to the item's content.
Upon saving the changes, you'll notice that the main item remains unaffected, while the changes are reflected only in the modified version.
Promoting a version makes it the main (current) version of your content.
Once promoted, this version becomes the active content, and the previous main item is preserved in the version history.
After promoting a version, you can choose to keep or delete the version. For the global draft version, you'll see options to "Discard Edits" or "Keep Edits" instead of "Delete Version" or "Keep Version".
::callout{icon="material-symbols:info-outline"}
Programmatically Implement Content Versioning
You have the option to integrate Content Versioning through the API. To learn how to accomplish this, please refer to
our API reference documentation.
::
Both Live Preview and the Visual Editor support version-aware previews, but they are configured differently.
Live Preview is configured per-collection in Settings → Data Model.
{{$version}} variable in the URLhttps://your-site.com/{{slug}}?preview=true&version={{$version}}Directus passes the selected version key as the version query parameter. Your frontend must read this and fetch versioned content from the API (e.g. /items/posts/42?version=draft). See Live Preview for full setup details.
The Visual Editor is configured globally in Settings → Visual Editor.
{{$version}} template variable in your URLhttps://your-site.com/preview?version={{$version}}The {{$version}} variable passes the selected version key to your website and ensures edits are saved to the selected version. See the Studio Module documentation for full setup details.
Under the hood, revisions are stored in the directus_revisions collection. In bigger projects this collection
can get large.
You can manage revision retention in two ways:
directus_revisions collection. Note that manual deletion may unintentionally remove content versions that are still in use, so exercise caution when performing bulk deletions.When implementing retention policies, consider your team's workflow and how far back you may need to revert changes before removing older revisions.
You can view revisions for an item within the right sidebar of the Studio. How many fields were updated in each revision is clarified via the label e.g. "Updated 2 Fields". Clicking on a revision will launch the content comparison modal.
Upon selecting a revision, you will see the differences between the previous revision (indicated on the left) and the current revision (indicated on the right), showing what changed in this revision.
Note that once the revisions comparison modal is open, you can change the revision selection via the dropdown menu at the top right of the modal.
Use the comparison toggle to switch between comparing the selected revision against its previous revision or against the latest revision.
When comparing against the latest revision, you can click Apply to restore the selected revision. This allows you to preview exactly what will change before committing to the restoration.
When a collapsed group interface contains fields with updates or differences, a diff indicator appears next to the group name.
When expanded, diff indicators are displayed next to each field in the group that has updates or differences.
When working with content versioning through the API, it's important to understand how items and their versions are represented differently.
When fetching items from a collection endpoint /items/{collection}, you receive the main version data:
{
"data": [
{
"id": 1,
"name": "Lion King",
"author": 1,
"release_date": "2025-10-01T12:00:00"
}
]
}
When fetching versions from the /versions/{version} endpoint, each version contains metadata and a delta object that shows the changes made in that version:
{
"data": {
"id": "0e0a8110-3cab-4bfb-93d5-17662588d0d4",
"key": "version-x",
"name": "version-x",
"collection": "books",
"item": "1",
"hash": "3284251037784c38c5bada022e579d3a484b4a09",
"date_created": "2025-10-14T08:58:21.279Z",
"date_updated": "2025-10-14T09:02:55.682Z",
"user_created": "ec5f6af5-b113-4b0a-9792-67596a547fd8",
"user_updated": "ec5f6af5-b113-4b0a-9792-67596a547fd8",
"delta": {
"id": "1",
"author": 2,
"release_date": "2025-10-05T12:00:00"
}
}
}
The delta object contains only the modified fields, making it easy to see exactly what changed in each version compared to the state of main at the time that version was created.