20 KiB
description, readTime, pageClass
| description | readTime | pageClass |
|---|---|---|
| REST and GraphQL API documentation to access and manage Items in Directus. | 5 min read | page-reference |
Accessing Items
Items are individual pieces of data in your database. They can be anything, from articles, to IoT status checks. Learn more about Items.
The Item Object
Items don't have a predefined schema. The format depends completely on how you configured your collections and fields in
Directus. For the sake of documentation, we'll use a fictional articles collection with the following fields: id,
status, title, body, featured_image, and author.
::: tip Relational Data
By default, the item object doesn't contain nested relational data. To retrieve nested data, see Relational Data and Field Parameters.
:::
{
"id": 1,
"status": "published",
"title": "Hello, world!",
"body": "This is my first article",
"featured_image": "768eabec-3c54-4110-a6bb-64b548116661",
"author": "0bc7b36a-9ba9-4ce0-83f0-0a526f354e07"
}
Get Items
List all items that exist in Directus.
Request
GET /items/:collection
SEARCH /items/:collection
If using SEARCH you can provide a query object as the body of your request.
POST /graphql
type Query {
<collection>: [<collection>]
}
import { createDirectus, rest, readItems } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(readItems('collection_name', query_object));
Query Parameters
Supports all global query parameters.
::: tip Relational Data
The Field Parameter is required to return nested relational data.
:::
Response
An array of up to limit item objects. If no items are available, data will be an empty array.
Example
GET /items/articles
SEARCH /items/articles
POST /graphql
query {
articles {
id
title
author {
first_name
}
}
}
import { createDirectus, rest, readItems } from '@directus/sdk';
const client = createDirectus('https://directus.example.com').with(rest());
const result = await client.request(
readItems('posts', {
fields: ['*'],
})
);
Get Item by ID
Get an item that exists in Directus.
Request
GET /items/:collection/:id
POST /graphql
type Query {
<collection>_by_id(id: ID!, version: String): <collection>
}
type Query {
<collection>_by_version(id: ID!, version: String!): <collection_version_raw>
}
import { createDirectus, rest, readItem } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(readItem(collection_name, item_id, query_object));
Query Parameters
Supports all global query parameters.
Additionally, supports a version parameter to retrieve an item's state from a specific
Content Version. The value corresponds to the key of the Content Version.
Response
Returns an item object if a valid primary key was provided.
Example
GET /items/articles/15
POST /graphql
query {
articles_by_id(id: 15) {
id
title
body
}
}
import { createDirectus, rest, readItem } from '@directus/sdk';
const client = createDirectus('https://directus.example.com').with(rest());
const result = await client.request(readItem('articles', '15'));
For a specific Content Version:
GET /items/articles/15
?version=draft
POST /graphql
query {
articles_by_version(id: 15, version: "draft") {
id
title
body
}
}
import { createDirectus, rest, readItem } from '@directus/sdk';
const client = createDirectus('https://directus.example.com').with(rest());
const result = await client.request(readItem('articles', '1', { version: 'draft' }));
Get Singleton
List a singleton item in Directus.
Request
GET /items/:collection
POST /graphql
type Query {
<collection>(version: String): <collection>
}
type Query {
<collection>_by_version(version: String!): <collection_version_raw>
}
import { createDirectus, rest, readSingleton } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(readSingleton(collection_name));
::: tip Info
The REST and GraphQL requests for singletons are the same as those used to Get Items but in contrast the response consists of a plain item object (the singleton) instead of an array of items.
:::
Query Parameters
Supports all global query parameters.
Additionally, supports a version parameter to retrieve a singleton's state from a specific
Content Version. The value corresponds to the key of the Content Version.
Request Body
collection_name the name of the collection is required.
Response
Returns an item object if a valid collection name was provided.
Example
GET /items/about
POST /graphql
query {
about {
id
content
}
}
import { createDirectus, rest, readSingleton } from '@directus/sdk';
const client = createDirectus('https://directus.example.com').with(rest());
const result = await client.request(readSingleton('about'));
For a specific Content Version:
GET /items/about
?version=draft
POST /graphql
query {
about_by_version(version: "draft") {
id
content
}
}
import { createDirectus, rest, readSingleton } from '@directus/sdk';
const client = createDirectus('https://directus.example.com').with(rest());
const result = await client.request(readSingleton('about', { version: 'draft' }));
Create an Item
Create a new item in the given collection.
Request
POST /items/:collection
Provide an item object as the body of your request.
POST /graphql
type Mutation {
create_<collection>_item(data: create_<collection>_input): <collection>
}
import { createDirectus, rest, createItem } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(createItem(collection_name, item_object));
Query Parameters
Supports all global query parameters.
Request Body
A partial item objects.
::: tip Relational Data
Relational data needs to be correctly nested to add new items successfully. Check out the relational data section for more information.
:::
Response
Returns the item objects of the item that were created.
Example
POST /items/articles
{
"title": "Hello world!",
"body": "This is our first article"
}
POST /graphql
mutation {
create_articles_item(data: { title: "Hello world!", body: "This is our first article" }) {
id
title
}
}
import { createDirectus, rest, createItem } from '@directus/sdk';
const client = createDirectus('https://directus.example.com').with(rest());
const result = await client.request(
createItem('articles', {
title: 'What is Directus?',
content: 'Directus is an Open Data Platform built to democratize the database.',
})
);
Create Multiple Items
Create new items in the given collection.
Request
POST /items/:collection
Provide an array of item object as the body of your request.
POST /graphql
type Mutation {
create_<collection>_items(data: [create_<collection>_input]): [<collection>]
}
import { createDirectus, rest, createItems } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(createItems(collection_name, item_object_array));
Query Parameters
Supports all global query parameters.
Request Body
An array of partial item objects.
Response
Returns the item objects of the item that were created.
Example
POST /items/articles
[
{
"title": "Hello world!",
"body": "This is our first article"
},
{
"title": "Hello again, world!",
"body": "This is our second article"
}
]
POST /graphql
mutation {
create_articles_items(
data: [
{ title: "Hello world!", body: "This is our first article" }
{ title: "Hello again, world!", body: "This is our second article" }
]
) {
id
title
}
}
import { createDirectus, rest, createItems } from '@directus/sdk';
const client = createDirectus('https://directus.example.com').with(rest());
const result = await client.request(
createItems('articles', [
{
title: 'What is Directus?',
content: 'Directus is an Open Data Platform built to democratize the database.',
},
{
title: 'Build your internal tools with Directus',
content: 'Flows enable custom, event-driven data processing and task automation within Directus.',
},
])
);
Update an Item
Update an existing item.
Request
PATCH /items/:collection/:id
Provide a partial item object as the body of your request.
POST /graphql
type Mutation {
update_<collection>_item(id: ID!, data: update_<collection>_input!): <collection>
}
import { createDirectus, rest, updateItem } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(updateItem(collection_name, item_id, partial_item_object));
Query Parameters
Supports all global query parameters.
Request Body
A partial item object.
Response
Returns the item object of the item that was updated.
Example
PATCH /items/articles/15
{
"title": "An updated title"
}
POST /graphql
mutation {
update_articles_item(id: 15, data: { title: "An updated title" }) {
id
title
}
}
import { createDirectus, rest, updateItem } from '@directus/sdk';
const client = createDirectus('https://directus.example.com').with(rest());
const result = await client.request(
updateItem('articles', '5', {
title: 'What is Directus and how it can help you build your next app!?',
})
);
Update Singleton
Update a singleton item.
Request
PATCH /items/:collection
Provide a partial item object as the body of your request.
POST /graphql
type Mutation {
update_<collection>_items(data: [update_<collection>_input]): [<collection>]
}
import { createDirectus, rest, updateSingleton } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(updateSingleton(collection_name, partial_item_object));
::: tip Info
The REST and GraphQL requests for singletons are the same as those used to Update Multiple Items but in contrast the request should consist of the plain item object.
:::
Query Parameters
Supports all global query parameters.
Request Body
The name of the collection collection_name is required and a partial item object.
Response
Returns the item object of the singleton that was updated.
Example
PATCH /items/about
{
"content": "Founded in 2023, this website is dedicated to..."
}
POST /graphql
mutation {
update_articles_items(data: { content: "Founded in 2023, this website is dedicated to..." }) {
content
}
}
import { createDirectus, rest, updateSingleton } from '@directus/sdk';
const client = createDirectus('https://directus.example.com').with(rest());
const result = await client.request(
updateSingleton('about', {
content: 'Founded in 2023, this website is dedicated to...',
})
);
Update Multiple Items
Update multiple items at the same time.
Request
PATCH /items/:collection
Provide a partial item object as the body of your request.
POST /graphql
type Mutation {
update_<collection>_items(ids: [ID!]!, data: [update_<collection>_input]): [<collection>]
}
import { createDirectus, rest, updateItems } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(updateItems(collection_name, item_id_array, partial_item_object));
Query Parameters
Supports all global query parameters.
Request Body
Object containing data for the values to set, and either keys or query to select what items to update.
Response
Returns the item objects for the updated items.
Example
PATCH /items/articles
{
"keys": [1, 2],
"data": {
"status": "published"
}
}
POST /graphql
mutation {
update_articles_items(ids: [1, 2], data: { status: "published" }) {
id
status
}
}
import { createDirectus, rest, updateItems } from '@directus/sdk';
const client = createDirectus('https://directus.example.com').with(rest());
const result = await client.request(
updateItems('articles', ['5', '6'], {
status: 'published',
})
);
Delete an Item
Delete an existing item.
Request
DELETE /items/:collection/:id
POST /graphql
type Mutation {
delete_<collection>_item(id: ID!): delete_one
}
import { createDirectus, rest, deleteItem } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(deleteItem(collection_name, item_id));
Response
Empty body.
Example
DELETE /items/articles/15
POST /graphql
mutation {
delete_articles_item(id: 15) {
id
}
}
import { createDirectus, rest, deleteItem } from '@directus/sdk';
const client = createDirectus('https://directus.example.com').with(rest());
const result = await client.request(deleteItem('articles', '5'));
Delete Multiple Items
Delete multiple existing items.
DELETE /items/:collection
Provide an array of item primary keys or an object containing either keys or query as your request body.
POST /graphql
type Mutation {
delete_<collection>_items(ids: [ID!]!): delete_many
}
import { createDirectus, rest, deleteItems } from '@directus/sdk';
const client = createDirectus('https://directus.example.com').with(rest());
const result = await client.request(deleteItems(collection_name, item_id_array));
//or
const result = await client.request(deleteItems(collection_name, query_object));
Query Parameters
Supports all global query parameters.
Request Body
An array of item primary keys or an object containing either keys or query to select what items to update.
Response
Empty body.
Example
DELETE /items/articles
// Array of primary keys
[15, 16, 21]
// Object containing keys
{
"keys": [15, 16, 21]
}
// Object containing query
{
"query": {
"filter": {
"status": {
"_eq": "draft"
}
}
}
}
POST /graphql
mutation {
delete_articles_items(ids: [15, 16, 21]) {
ids
}
}
import { createDirectus, rest, deleteItems } from '@directus/sdk';
const client = createDirectus('https://directus.example.com').with(rest());
const result = await client.request(deleteItems('articles', ['6', '7']));
//or
const result = await client.request(
deleteItems('articles', {
filter: {
status: {
_eq: 'draft',
},
},
})
);