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

Please see Relational Data and Field Parameters to learn more.

:::

{
	"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.

Query Parameters

Supports all global query parameters.

::: tip Relational Data

The Field Parameter is required to return nested relational data.

:::

Returns

An array of up to limit item objects. If no items are available, data will be an empty array.

Singleton

If your collection is a singleton, this endpoint will return the item. If the item doesn't exist in the database, the default values will be returned.

REST API

GET /items/:collection
SEARCH /items/:collection

Learn more about SEARCH ->

Example

GET /items/articles

GraphQL

POST /graphql

type Query {
	<collection>: [<collection>]
}

Example

query {
	articles {
		id
		title
		author {
			first_name
		}
	}
}

---

Get Item by ID

Get an item that exists in Directus.

Query Parameters

Supports all global query parameters.

Returns

Returns an item object if a valid primary key was provided.

REST API

GET /items/:collection/:id

Example

GET /items/articles/15

GraphQL

POST /graphql

type Query {
	<collection>_by_id(id: ID!): <collection>
}

Example

query {
	articles_by_id(id: 15) {
		id
		title
	}
}

---

Create an Item

Create a new item in the given collection.

Query Parameters

Supports all global query parameters.

Request Body

An array of 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.

:::

Returns

Returns the item objects of the item that were created.

REST API

POST /items/:collection

Example

POST /items/articles

{
	"title": "Hello world!",
	"body": "This is our first article"
}

GraphQL

POST /graphql

type Mutation {
	create_<collection>_item(data: create_<collection>_input): <collection>
}

Example

mutation {
	create_articles_item(data: { title: "Hello world!", body: "This is our first article" }) {
		id
		title
	}
}

---

Create Multiple Items

Create new items in the given collection.

Query Parameters

Supports all global query parameters.

Request Body

An array of partial item objects.

Returns

Returns the item objects of the item that were created.

REST API

POST /items/:collection

Example

POST /items/articles

[
	{
		"title": "Hello world!",
		"body": "This is our first article"
	},
	{
		"title": "Hello again, world!",
		"body": "This is our second article"
	}
]

GraphQL

POST /graphql

type Mutation {
	create_<collection>_items(data: [create_<collection>_input]): [<collection>]
}

Example

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

---

Update an Item

Update an existing item.

Query Parameters

Supports all global query parameters.

Request Body

A partial item object.

Returns

Returns the item object of the item that was updated.

REST API

PATCH /items/:collection/:id

Example

PATCH /items/articles/15

{
	"title": "An updated title"
}

GraphQL

POST /graphql

type Mutation {
	update_<collection>_item(id: ID!, data: update_<collection>_input!): <collection>
}

Example

mutation {
	update_articles_item(id: 15, data: { title: "An updated title" }) {
		id
		title
	}
}

---

Update Multiple Items

Update multiple items at the same time.

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.

Returns

Returns the item objects for the updated items.

Singleton

If your collection is a singleton, this endpoint will act the same as the Update an Item endpoint.

REST API

PATCH /items/:collection

Example

PATCH /items/articles

{
	"keys": [1, 2],
	"data": {
		"status": "published"
	}
}

GraphQL

POST /graphql

type Mutation {
	update_<collection>_items(ids: [ID!]!, data: [update_<collection>_input]): [<collection>]
}

Example

mutation {
	update_articles_items(ids: [1, 2], data: { status: "published" }) {
		id
		status
	}
}

---

Delete an Item

Delete an existing item.

Returns

Empty body.

REST API

DELETE /items/:collection/:id

Example

DELETE /items/articles/15

GraphQL

POST /graphql

type Mutation {
	delete_<collection>_item(id: ID!): delete_one
}

Example

mutation {
	delete_articles_item(id: 15) {
		id
	}
}

---

Delete Multiple Items

Delete multiple existing items.

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.

Returns

Empty body.

REST API

DELETE /items/:collection

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

GraphQL

POST /graphql

type Mutation {
	delete_<collection>_items(ids: [ID!]!): delete_many
}

Example

mutation {
	delete_articles_items(ids: [15, 16, 21]) {
		ids
	}
}