Accessing 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 predefined 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.

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

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 ​

Object containing data for the values to set, and either keys or query to select what items to update.

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