# 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.

Endpoint
   GET /:project/items/:collection
Response
{
  "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.

Endpoint
   GET /:project/items/:collection/:id
Response
{
  "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.

Endpoint
  POST /:project/items/:collection
Request
{
  "status": "published",
  "title": "Hello, world!",
  "body": "This is my first article",
  "featured_image": 2,
  "author": 5
}
Response
{
  "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.

Endpoint
 PATCH /:project/items/:collection/:id
Request
{
  "title": "Welcome!"
}
Response
{
  "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

Endpoint
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.

Endpoint
   GET /:project/items/:collection/:id/revisions
Response
{
  "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.

Endpoint
   GET /:project/items/:collection/:id/revisions/:offset
Response
{
  "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.

Endpoint
 PATCH /:project/items/:collection/:id/revert/:revision
Response
{
  "data": {
    "id": 14,
    "status": "published",
    "title": "Welcome!",
    "body": "This is my first article",
    "featured_image": 2,
    "author": 5
  }
}