Directus Docs

# Items: Data Access

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

# Get 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. If the item doesn't exist in the database, the default values will be returned.

# REST API

GET /items/:collection
SEARCH /items/:collection

Learn more about SEARCH ->

# Example
GET /items/articles

# GraphQL

POST /graphql

type Query {
	<collection>: [<collection>]
}
# Example
query {
	articles {
		id
		title
		author {
			first_name
		}
	}
}

# Get Item by ID

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.

# REST API

GET /items/:collection/:id
# Example
GET /items/articles/15

# GraphQL

POST /graphql

type Query {
	<collection>_by_id(id: ID!): <collection>
}
# Example
query {
	articles_by_id(id: 15) {
		id
		title
	}
}

# Create an Item

Create a new item in the given collection.

# Query Parameters

Supports all global query parameters.

# Request Body

An array of partial item objects.

Nested Data (Relations)

Relational data needs to be correctly nested to add new items successfully. Check out the relational data section for more information

# Returns

Returns the item objects of the item that were created.

# REST API

POST /items/:collection
# Example
POST /items/articles

{
	"title": "Hello world!",
	"body": "This is our first article"
}

# GraphQL

POST /graphql

type Mutation {
	create_<collection>_item(data: create_<collection>_input): <collection>
}
# Example
mutation {
	create_articles_item(data: { title: "Hello world!", body: "This is our first article" }) {
		id
		title
	}
}

# Create Multiple Items

Create new items in the given collection.

# Query Parameters

Supports all global query parameters.

# Request Body

An array of partial item objects.

# Returns

Returns the item objects of the item that were created.

# REST API

POST /items/:collection
# Example
POST /items/articles

[
	{
		"title": "Hello world!",
		"body": "This is our first article"
	},
	{
		"title": "Hello again, world!",
		"body": "This is our second article"
	}
]

# GraphQL

POST /graphql

type Mutation {
	create_<collection>_items(data: [create_<collection>_input]): [<collection>]
}
# Example
mutation {
	create_articles_items(
		data: [
			{ title: "Hello world!", body: "This is our first article" }
			{ title: "Hello again, world!", body: "This is our second article" }
		]
	) {
		id
		title
	}
}

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

# REST API

PATCH /items/:collection/:id
# Example
PATCH /items/articles/15

{
	"title": "An updated title"
}

# GraphQL

POST /graphql

type Mutation {
	update_<collection>_item(id: ID!, data: update_<collection>_input!): <collection>
}
# Example
mutation {
	update_articles_item(id: 15, data: { title: "An updated title" }) {
		id
		title
	}
}

# Update Multiple Items

Update multiple items at the same time.

# Query Parameters

Supports all global query parameters.

# Request Body

An array of partial item objects.

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

# REST API

PATCH /items/:collection
# Example
PATCH /items/articles

{
	"keys": [1, 2],
	"data": {
		"status": "published"
	}
}

# GraphQL

POST /graphql

type Mutation {
	update_<collection>_items(ids: [ID!]!, data: [update_<collection>_input]): [<collection>]
}
# Example
mutation {
	update_articles_items(ids: [1, 2], data: { status: "published" }) {
		id
		status
	}
}

# Delete an Item

Delete an existing item.

# Returns

Empty body.

# REST API

DELETE /items/:collection/:id
# Example
DELETE /items/articles/15

# GraphQL

POST /graphql

type Mutation {
	delete_<collection>_item(id: ID!): delete_one
}
# Example
mutation {
	delete_articles_item(id: 15) {
		id
	}
}

# Delete Multiple Items

Delete multiple existing items.

# Request Body

An array of item primary keys.

# Returns

Empty body.

# REST API

DELETE /items/:collection
# Example
DELETE /items/articles

[15, 16, 21]

# GraphQL

POST /graphql

type Mutation {
	delete_<collection>_items(ids: [ID!]!): delete_many
}
# Example
mutation {
	delete_articles_items(ids: [15, 16, 21]) {
		ids
	}
}

← Assets →