# 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 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. If the item doesn't exist in the database, the default values will be returned.
# 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.
# 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.
Nested Data (Relations)
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
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
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.
# Delete Multiple Items
Delete multiple existing items.