# Items: Data Access
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 pre-defined 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
.
{
"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.
Nested 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.
# Get Item by ID
Get an item that exists in Directus.
# Query Parameters
Supports all global query parameters.
# Returns
Returns a item object if a valid primary key was provided.
# 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.
# 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
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
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
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
An array of partial item objects.
# 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
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.
# Delete Multiple Items
Delete multiple existing items.