---
pageClass: page-reference
---
# Items
> Items are individual pieces of data in your database. They can be anything, from articles, to IoT status checks. [Learn more about Items](/concepts/items/).
[[toc]]
---
## 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`.
```json
{
"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](/reference/api/query).
::: tip Nested Data
The [Field Parameter](/reference/api/query/#fields) is required to return nested relational data!
:::
### Returns
An array of up to [limit](/reference/api/query/#limit) [item objects](#the-item-object). 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
```
```json
// 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](/reference/api/query).
### Returns
Returns a [item object](#the-item-object) if a valid primary key was provided.
```
GET /items/:collection/:id
```
```json
// 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](/reference/api/query).
### Request Body
A partial [item object](#the-item-object) or an array of partial [item objects](#the-item-object).
### Returns
Returns the [item object](#the-item-object) of the item that was created.
```
POST /items/:collection
```
```json
// Request
{
"title": "Hello again, world!",
"body": "This is our second article"
}
```
```json
// 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](/reference/api/query).
### Request Body
A partial [item object](#the-item-object).
### Returns
Returns the [item object](#the-item-object) of the item that was updated.
```
PATCH /items/:collection/:id
```
```json
// Request
{
"author": "d97c2e0e-293d-4eb5-9e1c-27d3460ad29d"
}
```
```json
// 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](/reference/api/query).
### 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](#the-item-object). 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](#the-item-object)'s properties.
### Returns
Returns the [item objects](#the-item-object) for the updated items.
#### Singleton
If your collection is a singleton, this endpoint will act the same as the [Update an Item](#update-an-item) endpoint.
```
PATCH /items/:collection
```
```json
// 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"
}
}
```
```json
// 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
```
```json
// Empty Response
```
---
## Delete Multiple Items
Delete multiple existing items.
### Request Body
An array of item primary keys.
### Returns
Empty body.
```
DELETE /items/:collection
```
```json
// Request
["d97c2e0e-293d-4eb5-9e1c-27d3460ad29d", "fc02d733-95b8-4e27-bd4b-08a32cbe4e66"]
```
```json
// Empty Response
```