# 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"
}
# List 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 /items/:collection
// Response
{
"data": [
{
"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"
},
{...},
{...}
]
}
# Retrieve an Item
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.
GET /items/:collection/:id
// Response
{
"data": {
"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"
}
}
# Create an Item
Create one or more new item(s).
# Query Parameters
Supports all global query parameters.
# Request Body
A partial item object or an array of partial item objects.
# Returns
Returns the item object of the item that was created.
POST /items/:collection
// Request
{
"title": "Hello again, world!",
"body": "This is our second article"
}
// Response
{
"data": {
"id": 2,
"status": "draft",
"title": "Hello, world!",
"body": "This is my first article",
"featured_image": null,
"author": null
}
}
# 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.
PATCH /items/:collection/:id
// Request
{
"author": "d97c2e0e-293d-4eb5-9e1c-27d3460ad29d"
}
// Response
{
"data": {
"id": 2,
"status": "draft",
"title": "Hello, world!",
"body": "This is my first article",
"featured_image": null,
"author": "d97c2e0e-293d-4eb5-9e1c-27d3460ad29d"
}
}
# Update Multiple Items
Update multiple items at the same time.
# Query Parameters
Supports all global query parameters.
# Request Body
There's two ways to update items: Update multiple items to different values, or to update multiple items to the same values.
# Different Values
Post an array of (partial) item objects. Make sure to include id for every object in the array in
order for Directus to be able to know what the item is you're updating.
# Same Value
Alternatively, you can send the following:
keys Required
Array of primary keys of the items you'd like to update.
data Required
Any of the item object's properties.
# 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.
PATCH /items/:collection
// Request
// Multiple items, different values
[
{
"id": 1,
"featured_image": "d17c10aa-0bad-4864-9296-84f522c753e5"
},
{
"id": 2,
"featured_image": "b6123925-2fc0-4a30-9d86-863eafc0a6e7"
}
]
// Multiple items, same value
{
"keys": [1, 2],
"data": {
"status": "published"
}
}
// Response
{
"data": [
{
"id": 2,
"status": "draft",
"title": "Hello, world!",
"body": "This is my first article",
"featured_image": null,
"author": null
},
{...}
]
}
# Delete an Item
Delete an existing item.
# Returns
Empty body.
DELETE /items/:collection/:id
// Empty Response
# Delete Multiple Items
Delete multiple existing items.
← Folders Permissions →