Items

Items are individual pieces of data in your database. They can be anything, from articles, to IoT status checks.

Endpoints
   GET /:project/items/:collection
   GET /:project/items/:collection/:id
  POST /:project/items/:collection
 PATCH /:project/items/:collection/:id
DELETE /:project/items/:collection/:id
   GET /:project/items/:collection/:id/revisions
   GET /:project/items/:collection/:id/revisions/:offset
 PATCH /:project/items/:collection/:id/revert/:revision

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.

Example Item Object
{
  "id": 1,
  "status": "published",
  "title": "Hello, world!",
  "body": "This is my first article",
  "featured_image": 2,
  "author": 5
}

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
  }
}