From eef47124130ea75d375ba6a896968b117ccb4c56 Mon Sep 17 00:00:00 2001 From: Nitwel Date: Tue, 3 Mar 2026 15:11:14 +0100 Subject: [PATCH 1/4] update version docs --- .../guides/04.connect/3.query-parameters.md | 27 +++++++++++++++---- 1 file changed, 22 insertions(+), 5 deletions(-) diff --git a/content/guides/04.connect/3.query-parameters.md b/content/guides/04.connect/3.query-parameters.md index 59e33434..41ba642f 100644 --- a/content/guides/04.connect/3.query-parameters.md +++ b/content/guides/04.connect/3.query-parameters.md @@ -535,13 +535,20 @@ Saves the API response to a file. Valid values are `csv`, `json`, `xml`, `yaml`. ## Version -Queries a version of a record by version key when [content versioning](/guides/content/content-versioning) is enabled on a collection. Applies only to single item retrieval. +Queries a version of a record by version key when [content versioning](/guides/content/content-versioning) is enabled on a collection. -```http [GET /items/posts/1] -?version=v1 +```http +GET /items/posts?version=v1 +GET /items/posts/1?version=v1 ``` ```graphql [GraphQL] +query { + posts(version: "v1") { + id + } +} + query { posts_by_id(id: 1, version: "v1") { id @@ -554,15 +561,25 @@ import { createDirectus, rest, readItem } from "@directus/sdk"; const directus = createDirectus("https://directus.example.com").with(rest()); const result = await directus.request( + readItems("posts", { + version: "v1", + }) +); + +const item = await directus.request( readItem("posts", { version: "v1", }) ); ``` +### Version Meta + +When retrieving a versioned item, an additional `$meta` field is included in the response, containing metadata such as the version key, the used delta and possibly an error message if the version failed to apply. + ## VersionRaw -Specifies to return relational delta changes as a [detailed output](https://directus.io/docs/guides/connect/relations#creating-updating-deleting) on a version record. +Specifies to return relational delta changes as a [detailed output](https://directus.io/docs/guides/connect/relations#creating-updating-deleting) on a version record. Applies only to single item retrieval. ```http [GET /items/posts/1] ?version=v1&versionRaw=true @@ -736,4 +753,4 @@ The articles collection consists of a many-to-one relation to Users called `auth } ``` -:: \ No newline at end of file +:: From e0a0da522b0f3a0f4a7f6b007a3a564fb1bdb891 Mon Sep 17 00:00:00 2001 From: Nitwel Date: Tue, 2 Jun 2026 13:26:06 +0200 Subject: [PATCH 2/4] update --- content/guides/04.connect/3.query-parameters.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/content/guides/04.connect/3.query-parameters.md b/content/guides/04.connect/3.query-parameters.md index fc3eb676..c31c22f0 100644 --- a/content/guides/04.connect/3.query-parameters.md +++ b/content/guides/04.connect/3.query-parameters.md @@ -594,13 +594,13 @@ import { createDirectus, rest, readItem } from "@directus/sdk"; const directus = createDirectus("https://directus.example.com").with(rest()); const result = await directus.request( - readItem("posts", { + readItems("posts", { version: "v1", }), ); const item = await directus.request( - readItem("posts", { + readItem("posts", 1, { version: "v1", }), ); @@ -608,13 +608,13 @@ const item = await directus.request( ### Version Meta -When retrieving a versioned item, an additional `$meta` field is included in the response, containing metadata such as the version key, the used delta and possibly an error message if the version failed to apply. +When retrieving a versioned item, an additional `$meta` field is included in the response, containing metadata such as the version key and possibly an error message if the version failed to apply. :: ## VersionRaw -Specifies to return relational delta changes as a [detailed output](https://directus.io/docs/guides/connect/relations#creating-updating-deleting) on a version record. +Specifies to return relational delta changes as a [detailed output](https://directus.io/docs/guides/connect/relations#creating-updating-deleting) on a version record. Applies only to single item retrieval. ```http [GET /items/posts/1] ?version=v1&versionRaw=true From 719d7523da02506e0aa94c2548fb171476794e29 Mon Sep 17 00:00:00 2001 From: daedalus <44623501+ComfortablyCoding@users.noreply.github.com> Date: Wed, 29 Jul 2026 16:57:42 -0400 Subject: [PATCH 3/4] adjustments --- .../guides/04.connect/3.query-parameters.md | 38 ++++++++++--------- 1 file changed, 21 insertions(+), 17 deletions(-) diff --git a/content/guides/04.connect/3.query-parameters.md b/content/guides/04.connect/3.query-parameters.md index 73b1b5ed..0e87bc75 100644 --- a/content/guides/04.connect/3.query-parameters.md +++ b/content/guides/04.connect/3.query-parameters.md @@ -569,18 +569,18 @@ The keys `published` and `draft` are reserved. Use `published` (or `main` for ba ::code-group -```http -GET /items/posts?version=v1 -GET /items/posts/1?version=v1 +```http [REST] +// Both item lists and single items are supported: + +GET /items/posts + ?version=v1 + +GET /items/posts/1 + ?version=v1 ``` ```graphql [GraphQL] -query { - posts(version: "v1") { - id - } -} - +# Only supported on single item and singleton reads, not collection-level queries. query { posts_by_id(id: 1, version: "v1") { id @@ -589,7 +589,7 @@ query { ``` ```js [SDK] -import { createDirectus, rest, readItem } from "@directus/sdk"; +import { createDirectus, rest, readItem, readItems } from "@directus/sdk"; const directus = createDirectus("https://directus.example.com").with(rest()); const result = await directus.request( @@ -605,18 +605,22 @@ const item = await directus.request( ); ``` -### Version Meta +:: -When retrieving a versioned item, an additional `$meta` field is included in the response, containing metadata such as the version key and possibly an error message if the version failed to apply. +### Version Meta -:: +Versioned items include an additional `$meta` field in the response. It contains `version_id`, which is the `id` of the record in `directus_versions`, not its `key`. When a version has no saved changes or could not be applied to the item, `$meta` also contains `delta`, plus an `error` object in the failure case. ## VersionRaw -Specifies to return relational delta changes as a [detailed output](https://directus.io/docs/guides/connect/relations#creating-updating-deleting) on a version record. Applies only to single item retrieval. +Specifies to return relational delta changes as a [detailed output](/guides/connect/relations#creating-updating-deleting) on a version record. Applies only to single item retrieval. -```http [GET /items/posts/1] -?version=v1&versionRaw=true +::code-group + +```http [REST] +GET /items/posts/1 + ?version=v1 + &versionRaw=true ``` ```graphql [GraphQL] @@ -632,7 +636,7 @@ import { createDirectus, rest, readItem } from "@directus/sdk"; const directus = createDirectus("https://directus.example.com").with(rest()); const result = await directus.request( - readItem("posts", { + readItem("posts", 1, { version: "v1", versionRaw: true, }), From 7860a164461dbaa16e0deaf50da9ce89dda1b889 Mon Sep 17 00:00:00 2001 From: daedalus <44623501+ComfortablyCoding@users.noreply.github.com> Date: Wed, 29 Jul 2026 17:23:56 -0400 Subject: [PATCH 4/4] add itemless note --- content/guides/04.connect/3.query-parameters.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/content/guides/04.connect/3.query-parameters.md b/content/guides/04.connect/3.query-parameters.md index 0e87bc75..e37d5c1d 100644 --- a/content/guides/04.connect/3.query-parameters.md +++ b/content/guides/04.connect/3.query-parameters.md @@ -611,6 +611,12 @@ const item = await directus.request( Versioned items include an additional `$meta` field in the response. It contains `version_id`, which is the `id` of the record in `directus_versions`, not its `key`. When a version has no saved changes or could not be applied to the item, `$meta` also contains `delta`, plus an `error` object in the failure case. +### Item-less Drafts + +[Item-less drafts](/guides/content/content-versioning#creating-new-items-as-drafts) appear in a list response with a `null` primary key, as the item does not exist in the collection yet. Likewise, any relational records created as part of the draft version also have `null` values. + +To read related records that already existed, request nested fields, for example `&fields=*,tags.*.*`{lang="http"}. + ## VersionRaw Specifies to return relational delta changes as a [detailed output](/guides/connect/relations#creating-updating-deleting) on a version record. Applies only to single item retrieval.