Content Versioning

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.

Concepts

• Version: a version of an item is a snapshot that gets copied from the current version or main item, allowing you to safely make changes and later promote to be the main item.
• Main: the main item is the default item that is displayed to users. It is the "source of truth" for all versions.
• Promote: when a version is promoted, it becomes the main item that is displayed to users.
• Revision: revisions are individual changes to items made within a version or main item. Directus keeps track of all changes made, so you're able to view the history of modifications and revert to a previous state.

Setting Up Content Versioning

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.

Creating a New Version

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.

Making Changes to a Version

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.

Comparing and Promoting a Version

Promoting a version makes it the main (current) version of your content.

How to Promote a Version

1. Open the version you want to promote
2. Select the "Promote Version" option from the dropdown.
3. In the comparison modal, review the changes:
   • Fields with differences from the main item are highlighted with color indicators
   • Review each highlighted field to understand what will change
4. Accept or reject individual changes as needed
5. Click "Promote" to finalize and make this version the new main item

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.

Revisions and Content Versioning

Under the hood, revisions are stored in the directus_revisions collection. In bigger projects this collection can get large.

Managing Revision Retention

You can manage revision retention in two ways:

• Automatic Retention Policies: Configure environment variables to automatically control how long revisions are kept. This allows you to balance the need for historical data with storage and performance considerations. See the Log Retention documentation for configuration options.
• Manual Cleanup: Periodically remove some or all data from the 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.

Viewing and Restoring 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.

Note that once the comparison modal is open, you can change the revision you want to compare by using the dropdown menu at the top right of the modal.

Upon selecting a revision, you will see the differences between the current version (indicated on the left) and that revision (indicated on the right).

The 'Updated' label indicators demonstrate which fields were updated in that revision, while the change indicators assist in understanding how the selected revision currently compares to the version it is associated with. If the revision is not associated with a version, the comparison will be against the main item.

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.

This can be mitigated by periodically removing some or all data in this collection. Note that this could unintentionally remove some content versions.

API Response Structure

When working with content versioning through the API, it's important to understand how items and their versions are represented differently.

Standard Item Response

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

Version Response

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.