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.
Relational Data
By default, the item object doesn't contain nested relational data. To retrieve nested data, see Relational Data and Field Parameters.
{
"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"
}{
"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.
Request
Query Parameters
Supports all global query parameters.
Relational Data
The Field Parameter is required to return nested relational data.
Response
An array of up to limit item objects. If no items are available, data will be an empty array.
Example
Get Item by ID
Get an item that exists in Directus.
Request
Query Parameters
Supports all global query parameters.
Additionally, supports a version parameter to retrieve an item's state from a specific Content Version. The value corresponds to the key of the Content Version.
Response
Returns an item object if a valid primary key was provided.
Example
For a specific Content Version:
Get Singleton
List a singleton item in Directus.
Request
Info
The REST and GraphQL requests for singletons are the same as those used to Get Items but in contrast the response consists of a plain item object (the singleton) instead of an array of items.
Query Parameters
Supports all global query parameters.
Additionally, supports a version parameter to retrieve a singleton's state from a specific Content Version. The value corresponds to the key of the Content Version.
Request Body
collection_name the name of the collection is required.
Response
Returns an item object if a valid collection name was provided.
Example
For a specific Content Version:
Create an Item
Create a new item in the given collection.
Request
Query Parameters
Supports all global query parameters.
Request Body
A partial item objects.
Relational Data
Relational data needs to be correctly nested to add new items successfully. Check out the relational data section for more information.
Response
Returns the item objects of the item that were created.
Example
Create Multiple Items
Create new items in the given collection.
Request
Query Parameters
Supports all global query parameters.
Request Body
An array of partial item objects.
Response
Returns the item objects of the item that were created.
Example
Update an Item
Update an existing item.
Request
Query Parameters
Supports all global query parameters.
Request Body
A partial item object.
Response
Returns the item object of the item that was updated.
Example
Update Singleton
Update a singleton item.
Request
Info
The REST and GraphQL requests for singletons are the same as those used to Update Multiple Items but in contrast the request should consist of the plain item object.
Query Parameters
Supports all global query parameters.
Request Body
The name of the collection collection_name is required and a partial item object.
Response
Returns an item object if a valid primary key was provided.
Example
Update Multiple Items
Update multiple items at the same time.
Request
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.
Response
Returns the item objects for the updated items.
Example
Delete an Item
Delete an existing item.
Request
Response
Empty body.
Example
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.
Response
Empty body.