Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/directus/directus/llms.txt

Use this file to discover all available pages before exploring further.

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