GET /:project/items/:collection
# Items
Items are individual pieces of data in your database. They can be anything, from articles, to IoT status checks.
# 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
.
# List the Items
List the items.
# Parameters
# project required
The project you're targetting.
# collection required
Unique identifier of the collection the item resides in.
# Query
# fields optional
Control what fields are being returned in the object. Learn more
# limit optional
A limit on the number of objects that are returned. Default is 200
. Learn more
# offset optional
How many items to skip when fetching data. Default is 0
. Learn more
# sort optional
How to sort the returned items. Learn more
# single optional
Return the result as if it was a single item. Useful for selecting a single item based on filters and search queries. Will force limit
to be 1. Learn more
# status optional
Filter items by the given status. Learn more
# filter optional
Select items in collection by given conditions. Learn more
# q optional
Filter by items that contain the given search query in one of their fields. Learn more
# meta optional
What metadata to return in the response. Learn more
# Returns
Returns an array of item objects.
{
"data": [
{
"id": 1,
"status": "published",
"title": "Hello, world!",
"body": "This is my first article",
"featured_image": 2,
"author": 5
},
{ ... },
{ ... }
]
}
# Retrieve an Item
Retrieve a single item by unique identifier.
# Parameters
# project required
The project you're targetting.
# collection required
Unique identifier of the collection the item resides in.
# id required
Unique identifier of the item.
# Query
# fields optional
Control what fields are being returned in the object. Learn more
# meta optional
What metadata to return in the response. Learn more
# Returns
Returns the item object for the given unique identifier.
GET /:project/items/:collection/:id
{
"data": {
"id": 1,
"status": "published",
"title": "Hello, world!",
"body": "This is my first article",
"featured_image": 2,
"author": 5
}
}
# Create an Item
Create a new item.
# Parameters
# project required
The project you're targetting.
# collection required
Unique identifier of the collection the item resides in.
# Attributes
Based on your specific setup.
# Query
# meta optional
What metadata to return in the response. Learn more
# Returns
Returns the item object for the item that was just created.
POST /:project/items/:collection
{
"status": "published",
"title": "Hello, world!",
"body": "This is my first article",
"featured_image": 2,
"author": 5
}
{
"data": {
"id": 14,
"status": "published",
"title": "Hello, world!",
"body": "This is my first article",
"featured_image": 2,
"author": 5
}
}
# Update an Item
Update an existing item.
# Parameters
# project required
The project you're targetting.
# collection required
Unique identifier of the collection the item resides in.
# id required
Unique identifier of the item.
# Attributes
Based on your specific setup.
# Query
# fields optional
Control what fields are being returned in the object. Learn more
# meta optional
What metadata to return in the response. Learn more
# Returns
Returns the item object for the item that was just updated.
PATCH /:project/items/:collection/:id
{
"title": "Welcome!"
}
{
"data": {
"id": 14,
"status": "published",
"title": "Welcome!",
"body": "This is my first article",
"featured_image": 2,
"author": 5
}
}
# Delete an Item
Delete an existing item
# Parameters
# project required
The project you're targetting.
# collection required
Unique identifier of the collection the item resides in.
# id required
Unique identifier of the item.
# Returns
Returns an empty body with HTTP status 204
DELETE /:project/items/:collection/:id
# List Item Revisions
List the revisions made to the given item.
# Parameters
# project required
The project you're targetting.
# collection required
Unique identifier of the collection the item resides in.
# id required
Unique identifier of the item.
# Query
# fields optional
Control what fields are being returned in the object. Learn more
# limit optional
A limit on the number of objects that are returned. Default is 200
. Learn more
# offset optional
How many items to skip when fetching data. Default is 0
. Learn more
# page optional
Cursor for use in pagination. Often used in combination with limit
. Learn more
# sort optional
How to sort the returned items. Learn more
# single optional
Return the result as if it was a single item. Useful for selecting a single item based on filters and search queries. Will force limit
to be 1. Learn more
# filter optional
Select items in collection by given conditions. Learn more
# q optional
Filter by items that contain the given search query in one of their fields. Learn more
# meta optional
What metadata to return in the response. Learn more
# Returns
Returns an array of revision objects.
GET /:project/items/:collection/:id/revisions
{
"data": [
{
"id": 35,
"activity": 37,
"collection": "articles",
"item": "14",
"data": {
"id": 14,
"status": "published",
"title": "Hello, World!",
"body": "This is my first article",
"featured_image": 2,
"author": 5
},
"delta": {
"title": "Welcome!"
},
"parent_collection": null,
"parent_item": null,
"parent_changed": false
},
{ ... },
{ ... }
]
}
# Retrieve an Item Revision
Retrieve a single revision of the item by offset.
# Parameters
# project required
The project you're targetting.
# collection required
Unique identifier of the collection the item resides in.
# offset required
How many revisions to go back in time.
# Query
# fields optional
Control what fields are being returned in the object. Learn more
# meta optional
What metadata to return in the response. Learn more
# Returns
Returns the revision object for the given unique identifier.
GET /:project/items/:collection/:id/revisions/:offset
{
"data": {
"id": 35,
"activity": 37,
"collection": "articles",
"item": "14",
"data": {
"id": 14,
"status": "published",
"title": "Hello, World!",
"body": "This is my first article",
"featured_image": 2,
"author": 5
},
"delta": {
"title": "Welcome!"
},
"parent_collection": null,
"parent_item": null,
"parent_changed": false
}
}
# Revert to a Given Revision
Revert the item to a given revision.
# Parameters
# project required
The project you're targetting.
# collection required
Unique identifier of the collection the item resides in.
# id required
Unique identifier of the item.
# revision required
Unique identifier of the revision to revert to.
# Attributes
No attributes available.
# Query
# fields optional
Control what fields are being returned in the object. Learn more
# meta optional
What metadata to return in the response. Learn more
# Returns
Returns the item object in its new state.
PATCH /:project/items/:collection/:id/revert/:revision
{
"data": {
"id": 14,
"status": "published",
"title": "Welcome!",
"body": "This is my first article",
"featured_image": 2,
"author": 5
}
}
← Authentication Files →