Items

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

List Items in a Collection

Returns a list of the items in the given collection.

Query Parameters

collection

string

Unique identifier of the collection the item resides in.

fields

array

Control what fields are being returned in the object.

limit

integer

A limit on the number of objects that are returned.

offset

integer

How many items to skip when fetching data.

page

integer

Cursor for use in pagination. Often used in combination with limit.

meta

string

What metadata to return in the response.

sort

array

How to sort the returned items. sort is a CSV of fields used to sort the fetched items. Sorting defaults to ascending (ASC) order but a minus sign (-) can be used to reverse this to descending (DESC) order. Fields are prioritized by their order in the CSV.

filter

Select items in collection by given conditions.

string

Filter by items that contain the given search query in one of their fields.

export

string

Saves the API response to a file. Accepts one of csv, csv_utf8, json, xml, yaml.

version

string

Retrieve an item's state from a specific Content Version. The value corresponds to the "key" of the Content Version.

versionRaw

boolean

Retrieve the raw delta of a Content Version item instead of the full merged item.

backlink

boolean

Retrieve relational items excluding reverse relations when using wildcard fields.

aggregate

Aggregate functions allow you to perform calculations on a set of values. Accepts one or more of count, countDistinct, countAll, sum, sumDistinct, avg, avgDistinct, min, max.

group

array

Grouping allows for running the aggregation functions based on a shared value. Accepts an array of field names.

deep

Deep allows you to set any of the other query parameters on a nested relational dataset. Use underscore-prefixed parameter names.

alias

Alias allows you to rename fields in the response payload. The key is the new name, the value is the original field name.

Responses

Successful request

data

array

import { createDirectus, rest, readItems } from '@directus/sdk';

const client = createDirectus('directus_project_url').with(rest());

const result = await client.request(readItems('collection_name', query_object));

GET /items/{collection}

type Query {
  <collection>: [<collection>]
}

Response Example

{
  "data": [
    {}
  ]
}

Create Multiple Items

Create new items in the given collection.

Query Parameters

collection

string

Collection of which you want to retrieve the items from.

fields

array

Control what fields are being returned in the object.

limit

integer

A limit on the number of objects that are returned.

offset

integer

How many items to skip when fetching data.

sort

array

filter

Select items in collection by given conditions.

string

Filter by items that contain the given search query in one of their fields.

meta

string

What metadata to return in the response.

Request Body

data

array

Responses

Successful request

data

array

meta

object

import { createDirectus, rest, createItems } from '@directus/sdk';

const client = createDirectus('directus_project_url').with(rest());

const result = await client.request(createItems(collection_name, item_object_array));

POST /items/{collection}

type Mutation {
  create_<collection>_items(data: [create_<collection>_input]): [<collection>]
}

Response Example

{
  "data": [
    {}
  ],
  "meta": {}
}

Delete Multiple Items

Delete multiple items at the same time.

Query Parameters

collection

string

Collection of which you want to retrieve the items from.

fields

array

Control what fields are being returned in the object.

limit

integer

A limit on the number of objects that are returned.

meta

string

What metadata to return in the response.

offset

integer

How many items to skip when fetching data.

sort

array

filter

Select items in collection by given conditions.

string

Filter by items that contain the given search query in one of their fields.

Request Body

[undefined]

Responses

The resource was deleted successfully.

import { createDirectus, rest, deleteItems } from '@directus/sdk';

const client = createDirectus('directus_project_url').with(rest());

const resultByKeys = await client.request(deleteItems(collection_name, item_id_array));

const resultByQuery = await client.request(deleteItems(collection_name, query_object));

DELETE /items/{collection}

type Mutation {
  delete_<collection>_items(ids: [ID!]!): delete_many
}

Update Multiple Items

Update multiple items at the same time.

Query Parameters

collection

string

Collection of which you want to retrieve the items from.

fields

array

Control what fields are being returned in the object.

limit

integer

A limit on the number of objects that are returned.

meta

string

What metadata to return in the response.

offset

integer

How many items to skip when fetching data.

sort

array

filter

Select items in collection by given conditions.

string

Filter by items that contain the given search query in one of their fields.

Request Body

[undefined]

Responses

Successful request

data

array

meta

object

import { createDirectus, rest, updateItems } from '@directus/sdk';

const client = createDirectus('directus_project_url').with(rest());

const resultByKeys = await client.request(updateItems(collection_name, item_id_array, partial_item_object));

const resultByQuery = await client.request(updateItems(collection_name, query_object, partial_item_object));

PATCH /items/{collection}

type Mutation {
  update_<collection>_items(ids: [ID!]!, data: update_<collection>_input!): [<collection>]
}

Response Example

{
  "data": [
    {}
  ],
  "meta": {}
}

Create an Item

Create a new item in the given collection.

Query Parameters

collection

string

Collection of which you want to retrieve the items from.

fields

array

Control what fields are being returned in the object.

meta

string

What metadata to return in the response.

Request Body

Responses

Successful request

data

object

import { createDirectus, rest, createItem } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(createItem(collection_name, item_object));

POST /items/{collection}‎

type Mutation {
  create_<collection>_item(data: create_<collection>_input): <collection>
}

Response Example

{
  "data": {}
}

Retrieve an Item

Retrieves an item in a given collection.

Query Parameters

string

Unique identifier for the object.

collection

string

Collection of which you want to retrieve the items from.

version

string

Retrieve an item's state from a specific Content Version. The value corresponds to the "key" of the Content Version.

fields

array

Control what fields are being returned in the object.

meta

string

What metadata to return in the response.

Responses

Successful request

data

object

import { createDirectus, rest, readItem } from '@directus/sdk';

const client = createDirectus('directus_project_url').with(rest());

const result = await client.request(readItem(collection_name, item_id, query_object));

GET /items/{collection}/{id}

type Query {
  <collection>_by_id(id: ID!, version: String): <collection>
}

type Query {
  <collection>_by_version(id: ID!, version: String!): <collection_version_raw>
}

Response Example

{
  "data": {}
}

Delete an Item

Delete an existing item.

Query Parameters

string

Unique identifier of the item.

collection

string

Collection of which you want to retrieve the items from.

Responses

The resource was deleted successfully.

import { createDirectus, rest, deleteItem } from '@directus/sdk';

const client = createDirectus('directus_project_url').with(rest());

const result = await client.request(deleteItem(collection_name, item_id));

DELETE /items/{collection}/{id}

type Mutation {
  delete_<collection>_item(id: ID!): delete_one
}

Update an Item

Update an existing item.

Query Parameters

string

Unique identifier of the item.

collection

string

Collection of which you want to retrieve the items from.

fields

array

Control what fields are being returned in the object.

meta

string

What metadata to return in the response.

Request Body

Responses

Successful request

data

object

import { createDirectus, rest, updateItem } from '@directus/sdk';

const client = createDirectus('directus_project_url').with(rest());

const result = await client.request(updateItem(collection_name, item_id, partial_item_object));

PATCH /items/{collection}/{id}

type Mutation {
  update_<collection>_item(id: ID!, data: update_<collection>_input!): <collection>
}

Response Example

{
  "data": {}
}

Retrieve a Singleton Item

Retrieve the singleton item from the given collection. Unlike regular collections, a singleton returns a plain item object rather than an array of items.

Query Parameters

collection

string

Collection of which you want to retrieve the items from.

fields

array

Control what fields are being returned in the object.

meta

string

What metadata to return in the response.

version

string

Retrieve an item's state from a specific Content Version. The value corresponds to the "key" of the Content Version.

versionRaw

boolean

Retrieve the raw delta of a Content Version item instead of the full merged item.

deep

Deep allows you to set any of the other query parameters on a nested relational dataset. Use underscore-prefixed parameter names.

alias

Alias allows you to rename fields in the response payload. The key is the new name, the value is the original field name.

Responses

Successful request

data

object

import { createDirectus, rest, readSingleton } from '@directus/sdk';

const client = createDirectus('directus_project_url').with(rest());

const result = await client.request(readSingleton('collection_name', query_object));

GET /items/{collection}‏

type Query {
  <collection>(version: String): <collection>
}

type Query {
  <collection>_by_version(version: String!): <collection_version_raw>
}

Response Example

{
  "data": {}
}

Update a Singleton Item

Update the singleton item in the given collection. Unlike batch updates for regular collections, the request body should be a plain item object rather than a keyed batch payload.

Query Parameters

collection

string

Collection of which you want to retrieve the items from.

fields

array

Control what fields are being returned in the object.

meta

string

What metadata to return in the response.

Request Body

Responses

Successful request

data

object

import { createDirectus, rest, updateSingleton } from '@directus/sdk';

const client = createDirectus('directus_project_url').with(rest());

const result = await client.request(updateSingleton('collection_name', partial_item_object));

PATCH /items/{collection}‏

type Mutation {
  update_<collection>(data: update_<collection>_input!): <collection>
}

Response Example

{
  "data": {}
}