20 KiB
description, readTime, pageClass
| description | readTime | pageClass |
|---|---|---|
| REST and GraphQL API documentation on the Versions collection in Directus. | 5 min read | page-reference |
Content Versions
Content Versioning enables users to create unpublished copies of an item (called "Content Versions"), modify them independently from the main version, and promote them to become the new main version when ready.
The Content Version Object
id uuid
Primary key of the Content Version.
key string
Key of the Content Version, used as the value for the version query parameter.
name string
Descriptive name of the Content Version.
collection string
Name of the collection the Content Version is created on.
item many-to-one
The item the Content Version is created on.
date_created Date
When the Content Version was created.
user_created many-to-one
User that created the Content Version. Many-to-one to users.
{
"id": "21a7ed5f-eb19-42ae-8ee2-61f25b8c4eb5",
"key": "my_version",
"name": "My Version",
"collection": "my_collection",
"item": "1",
"hash": "aaafc0db8fb60e82e634903523e1fa2144c58520",
"date_created": "2023-08-23T10:38:20.686Z",
"user_created": "a2dbc923-7c75-4d26-83f4-4674bfa7be81"
}
List Content Versions
List all Content Versions that exist in Directus.
Request
GET /versions
SEARCH /versions
If using SEARCH you can provide a query object as the body of your request.
POST /graphql/system
type Query {
versions: [directus_versions]
}
import { createDirectus, rest, readContentVersions } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(readContentVersions(query_object));
Query Parameters
Supports all global query parameters.
Response
An array of up to limit Content Version objects. If no items are available, data will be an empty array.
Example
GET /versions
SEARCH /versions
POST /graphql/system
query {
versions {
id
key
name
}
}
import { createDirectus, rest, readContentVersions } from '@directus/sdk';
const client = createDirectus('https://directus.example.com').with(rest());
const result = await client.request(
readContentVersions({
fields: ['*'],
})
);
Retrieve a Content Version
List an existing Content Version by primary key.
Request
GET /versions/:id
POST /graphql/system
type Query {
versions_by_id(id: ID!): directus_versions
}
import { createDirectus, rest, readContentVersion } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(readContentVersion(content_version_id, query_object));
Query Parameters
Supports all global query parameters.
Response
Returns the requested Content Version object.
Example
GET /versions/21a7ed5f-eb19-42ae-8ee2-61f25b8c4eb5
POST /graphql/system
query {
versions_by_id(id: "e35f7b9a-aabe-4a41-92b4-2bed97fd49ef") {
id
key
name
}
}
import { createDirectus, rest, readContentVersion } from '@directus/sdk';
const client = createDirectus('https://directus.example.com').with(rest());
const result = await client.request(
readContentVersion('dc2ac3f9-2076-4e86-8677-b47643eddacf', {
fields: ['*'],
})
);
Create a Content Version
Create a new Content Version for an item.
Request
POST /versions
Provide a Content Version object as the body of your request.
POST /graphql/system
type Mutation {
create_versions_item(data: create_directus_versions_input!): directus_versions
}
import { createDirectus, rest, createContentVersion } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(createContentVersion(content_version_object));
Query Parameters
Supports all global query parameters.
Request Body
A partial Content Version object.
Response
Returns the Content Version object for the created version.
Example
POST /versions
{
"key": "my_version",
"name": "My Version",
"collection": "my_collection",
"item": "1"
}
POST /graphql/system
mutation {
create_versions_item(data: { key: "my_version", name: "My Version", collection: "my_collection", item: "1" }) {
id
key
name
}
}
import { createDirectus, rest, createContentVersion } from '@directus/sdk';
const client = createDirectus('https://directus.example.com').with(rest());
const result = await client.request(
createContentVersion({
key: 'my_version',
name: 'My Version',
collection: 'my_collection',
item: 1,
})
);
Create Multiple Content Versions
Create multiple new Content Versions.
Request
POST /versions
Provide an array of Content Version objects as the body of your request.
POST /graphql/system
type Mutation {
create_versions_items(data: [create_directus_versions_input!]!): [directus_versions]
}
import { createDirectus, rest, createContentVersions } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(createContentVersions(content_version_object_array));
Query Parameters
Supports all global query parameters.
Request Body
An array of partial Content Version objects.
Response
Returns an array of Content Version objects for the created versions.
Example
POST /versions
[
{
"key": "my_version",
"name": "My Version",
"collection": "my_collection",
"item": 1
},
{
"key": "another_version",
"name": "Another Version",
"collection": "another_collection",
"item": 2
}
]
POST /graphql/system
mutation {
create_versions_items(
data: [
{ key: "my_version", name: "My Version", collection: "my_collection", item: "1" }
{ key: "another_version", name: "Another Version", collection: "another_collection", item: "2" }
]
) {
id
key
name
}
}
import { createDirectus, rest, createContentVersions } from '@directus/sdk';
const client = createDirectus('https://directus.example.com').with(rest());
const result = await client.request(
createContentVersions([
{
key: 'my_version',
name: 'My Version',
collection: 'my_collection',
item: 1,
},
{
key: 'another_version',
name: 'Another Version',
collection: 'another_collection',
item: 2,
},
])
);
Update a Content Version
Update an existing Content Version.
Request
PATCH /versions/:id
Provide a partial Content Version object as the body of your request.
POST /graphql/system
type Mutation {
update_versions_item(id: ID!, data: update_directus_versions_input!): directus_versions
}
import { createDirectus, rest, updateContentVersion } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(updateContentVersion(content_version_id, partial_content_version_object));
Query Parameters
Supports all global query parameters.
Request Body
A partial Content Version object.
Response
Returns the Content Version object for the updated version.
Example
PATCH /versions/21a7ed5f-eb19-42ae-8ee2-61f25b8c4eb5
{
"name": "My Updated Version"
}
POST /graphql/system
mutation {
update_versions_item(id: "21a7ed5f-eb19-42ae-8ee2-61f25b8c4eb5", data: { name: "My Updated Version" }) {
id
key
name
}
}
import { createDirectus, rest, updateContentVersion } from '@directus/sdk';
const client = createDirectus('https://directus.example.com').with(rest());
const result = await client.request(
updateContentVersion('21a7ed5f-eb19-42ae-8ee2-61f25b8c4eb5', {
name: 'My Updated Version',
})
);
Update Multiple Content Versions
Update multiple existing Content Versions.
Request
PATCH /versions
{
"keys": content_version_id_array,
"data": partial_content_version_object
}
POST /graphql/system
type Mutation {
update_versions_items(ids: [ID!]!, data: update_directus_versions_input!): [directus_versions]
}
import { createDirectus, rest, updateContentVersions } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(updateContentVersions(content_version_id_array, partial_content_version_object));
Query Parameters
Supports all global query parameters.
Request Body
keys Required
Array of primary keys of the Content Versions you'd like to update.
data Required
The name property of the Content Version object.
Response
Returns the Content Version objects for the updated versions.
Example
PATCH /versions
{
"keys": ["21a7ed5f-eb19-42ae-8ee2-61f25b8c4eb5", "31e1c0c6-b575-47fb-908a-baf81b4e5631"],
"data": {
"name": "My Updated Version"
}
}
POST /graphql/system
mutation {
update_versions_items(
ids: ["21a7ed5f-eb19-42ae-8ee2-61f25b8c4eb5", "31e1c0c6-b575-47fb-908a-baf81b4e5631"]
data: { name: "My Updated Version" }
) {
id
key
name
}
}
import { createDirectus, rest, updateContentVersions } from '@directus/sdk';
const client = createDirectus('https://directus.example.com').with(rest());
const result = await client.request(
updateContentVersions(['21a7ed5f-eb19-42ae-8ee2-61f25b8c4eb5', '31e1c0c6-b575-47fb-908a-baf81b4e5631'], {
name: 'My Updated Version',
})
);
Delete a Content Version
Delete an existing Content Version.
Request
DELETE /versions/:id
POST /graphql/system
type Mutation {
delete_versions_item(id: ID!): delete_one
}
import { createDirectus, rest, deleteContentVersion } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(deleteContentVersion(content_version_id));
Response
Empty body.
Example
DELETE /versions/21a7ed5f-eb19-42ae-8ee2-61f25b8c4eb5
POST /graphql/system
mutation {
delete_versions_item(id: "21a7ed5f-eb19-42ae-8ee2-61f25b8c4eb5") {
id
}
}
import { createDirectus, rest, deleteContentVersion } from '@directus/sdk';
const client = createDirectus('https://directus.example.com').with(rest());
const result = await client.request(deleteContentVersion('21a7ed5f-eb19-42ae-8ee2-61f25b8c4eb5'));
Delete Multiple Content Versions
Delete multiple existing Content Versions.
Request
DELETE /versions
Provide an array of Content Version IDs as the body of your request.
POST /graphql/system
type Mutation {
delete_versions_items(ids: [ID!]!): delete_many
}
import { createDirectus, rest, deleteContentVersions } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(deleteContentVersions(content_version_id_array));
Request Body
An array of Content Version primary keys
Response
Empty body.
Example
DELETE /versions
["21a7ed5f-eb19-42ae-8ee2-61f25b8c4eb5", "31e1c0c6-b575-47fb-908a-baf81b4e5631"]
POST /graphql/system
mutation {
delete_versions_items(ids: ["21a7ed5f-eb19-42ae-8ee2-61f25b8c4eb5", "31e1c0c6-b575-47fb-908a-baf81b4e5631"]) {
ids
}
}
import { createDirectus, rest, deleteContentVersions } from '@directus/sdk';
const client = createDirectus('https://directus.example.com').with(rest());
const result = await client.request(
deleteContentVersions(['21a7ed5f-eb19-42ae-8ee2-61f25b8c4eb5', '31e1c0c6-b575-47fb-908a-baf81b4e5631'])
);
Save to a Content Version
Save item changes to an existing Content Version.
Request
POST /versions/:id/save
Provide a partial item object as the body of your request.
// Not supported in GraphQL
import { createDirectus, rest, saveToContentVersion } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(saveToContentVersion(content_version_id, partial_item_object));
Response
Returns the item object with the new state after save.
Example
POST /versions/21a7ed5f-eb19-42ae-8ee2-61f25b8c4eb5/save
{
"my_field": "Updated Value"
}
// Not supported in GraphQL
import { createDirectus, rest, saveContentVersion } from '@directus/sdk';
const client = createDirectus('https://directus.example.com').with(rest());
const result = await client.request(
saveContentVersion('21a7ed5f-eb19-42ae-8ee2-61f25b8c4eb5', { my_field: 'Updated Value' })
);
Compare a Content Version
Compare an existing Content Version with the main version of the item.
Request
GET /versions/:id/compare
// Not supported in GraphQL
import { createDirectus, rest, compareContentVersion } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(compareContentVersion(content_version_id));
Response
Returns all fields with different values, along with the hash of the main version of the item and the information whether the Content Version is outdated (i.e. main version of the item has been updated since the creation of the Content Version):
{
"outdated": false,
"mainHash": "2ee9c4e33b19d2cdec66a1ff7355e75a331591d9",
"current": {
"my_field": "Updated Value"
},
"main": {
"my_field": "Main Value"
}
}
Example
GET /versions/21a7ed5f-eb19-42ae-8ee2-61f25b8c4eb5/compare
// Not supported in GraphQL
import { createDirectus, rest, compareContentVersion } from '@directus/sdk';
const client = createDirectus('https://directus.example.com').with(rest());
const result = await client.request(compareContentVersion('21a7ed5f-eb19-42ae-8ee2-61f25b8c4eb5'));
Promote a Content Version
Promote an existing Content Version to become the new main version of the item.
Request
POST /versions/:id/promote
Pass the current hash of the main version of the item (obtained from the compare endpoint) along with an optional
array of field names of which the values are to be promoted (by default, all fields are selected).
{
"mainHash": main_hash,
"fields": fields_name_array
}
// Not supported in GraphQL
import { createDirectus, rest, promoteContentVersion } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(promoteContentVersion(content_version_id, promote_object));
Response
The primary key of the promoted item.
Example
POST /versions/21a7ed5f-eb19-42ae-8ee2-61f25b8c4eb5/promote
{
"mainHash": "2ee9c4e33b19d2cdec66a1ff7355e75a331591d9",
"fields": ["my_field"]
}
// Not supported in GraphQL
import { createDirectus, rest, promoteContentVersion } from '@directus/sdk';
const client = createDirectus('https://directus.example.com').with(rest());
const result = await client.request(
promoteContentVersion('21a7ed5f-eb19-42ae-8ee2-61f25b8c4eb5', '2ee9c4e33b19d2cdec66a1ff7355e75a331591d9', [
'my_field',
])
);