Items

Create, read, update, and delete items in collections

Items are individual records in your collections. The Items API provides full CRUD operations.

List Items

Retrieve multiple items from a collection.

GET /items/:collection

collection · string · required

The collection name

Example:

curl "https://your-directus-instance.com/items/articles" \
  -H "Authorization: Bearer YOUR_TOKEN"

Query Parameters:

• fields - Select specific fields
• filter - Filter items
• sort - Sort results
• limit - Limit number of results
• offset or page - Pagination
• search - Full-text search
• meta - Include metadata (total count, filter count)

Response:

{
  "data": [
    {
      "id": 1,
      "title": "Hello World",
      "status": "published"
    }
  ]
}

Get Item by ID

Retrieve a single item by its primary key.

GET /items/:collection/:id

Example:

curl "https://your-directus-instance.com/items/articles/1" \
  -H "Authorization: Bearer YOUR_TOKEN"

Create Item

Create a new item in a collection.

POST /items/:collection

Request Body:

{
  "title": "My New Article",
  "status": "draft",
  "body": "Article content..."
}

Example:

curl -X POST "https://your-directus-instance.com/items/articles" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My New Article",
    "status": "draft"
  }'

Create Multiple Items

Create multiple items in a single request.

POST /items/:collection

Request Body:

[
  { "title": "Article 1", "status": "draft" },
  { "title": "Article 2", "status": "draft" }
]

Update Item

Update an existing item.

PATCH /items/:collection/:id

Request Body:

{
  "status": "published",
  "published_date": "2024-03-03"
}

Example:

curl -X PATCH "https://your-directus-instance.com/items/articles/1" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "published"
  }'

Update Multiple Items

Update multiple items with a single request.

PATCH /items/:collection

Request Body:

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

Delete Item

Delete an item.

DELETE /items/:collection/:id

Example:

curl -X DELETE "https://your-directus-instance.com/items/articles/1" \
  -H "Authorization: Bearer YOUR_TOKEN"

Delete Multiple Items

Delete multiple items.

DELETE /items/:collection

Request Body:

[1, 2, 3]

Advanced Filtering

Comparison Operators

# Equal
GET /items/articles?filter[status][_eq]=published

# Not equal
GET /items/articles?filter[status][_neq]=draft

# Greater than
GET /items/articles?filter[views][_gt]=1000

# Contains
GET /items/articles?filter[title][_contains]=directus

# In array
GET /items/articles?filter[status][_in]=published,archived

Logical Operators

# AND
GET /items/articles?filter[_and][0][status][_eq]=published&filter[_and][1][views][_gte]=100

# OR
GET /items/articles?filter[_or][0][status][_eq]=published&filter[_or][1][status][_eq]=archived

Nested Filtering

# Filter by related field
GET /items/articles?filter[author][name][_eq]=John

Sorting

# Ascending
GET /items/articles?sort=title

# Descending
GET /items/articles?sort=-date_created

# Multiple fields
GET /items/articles?sort=status,-date_created

Pagination

Limit & Offset

GET /items/articles?limit=25&offset=50

Page & Limit

GET /items/articles?page=3&limit=25

Metadata

GET /items/articles?meta=total_count,filter_count

Response:

{
  "data": [...],
  "meta": {
    "total_count": 156,
    "filter_count": 42
  }
}

Field Selection

# Specific fields
GET /items/articles?fields=id,title,status

# All fields
GET /items/articles?fields=*

# Related fields
GET /items/articles?fields=*,author.name,author.email

# Nested relationships
GET /items/articles?fields=*,author.*,author.role.name

Search

Full-text search across all fields:

GET /items/articles?search=directus

Aggregation

# Count
GET /items/articles?aggregate[count]=id

# Sum
GET /items/articles?aggregate[sum]=views

# Average
GET /items/articles?aggregate[avg]=rating

# Min/Max
GET /items/articles?aggregate[min]=date_created&aggregate[max]=date_created

Revisions

Access item revision history:

GET /items/articles/1/revisions
GET /items/articles/1/revisions/:revision_id

Next Steps

Collections

Manage collections

Fields

Manage fields