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

{
	"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.

Nested Data

The Field Parameter is required to return nested relational data!

# Returns

An array of up to limit item objects. 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
// 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.

# Returns

Returns a item object if a valid primary key was provided.

GET /items/:collection/:id
// 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.

# Request Body

A partial item object or an array of partial item objects.

# Returns

Returns the item object of the item that was created.

POST /items/:collection
// Request

{
	"title": "Hello again, world!",
	"body": "This is our second article"
}
// 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.

# Request Body

A partial item object.

# Returns

Returns the item object of the item that was updated.

PATCH /items/:collection/:id
// Request

{
	"author": "d97c2e0e-293d-4eb5-9e1c-27d3460ad29d"
}
// 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.

# 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. 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's properties.

# Returns

Returns the item objects for the updated items.

# Singleton

If your collection is a singleton, this endpoint will act the same as the Update an Item endpoint.

PATCH /items/:collection
// 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"
	}
}
// 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
// Empty Response

# Delete Multiple Items

Delete multiple existing items.

# Request Body

An array of item primary keys.

# Returns

Empty body.

DELETE /items/:collection
// Request
["d97c2e0e-293d-4eb5-9e1c-27d3460ad29d", "fc02d733-95b8-4e27-bd4b-08a32cbe4e66"]
// Empty Response