directus/docs/reference/items.md

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.

Learn more about SEARCH ->

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

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_id(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>]
}

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 singelton'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(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 an item object if a valid primary key was provided.

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',
			},
		},
	})
);