What are Items? Items are the individual pieces of data stored within collections. Each item represents a single row in a database table and contains values for all the fields defined in its parent collection. Items are the core content objects you create, read, update, and delete through the Directus API.
Every item is uniquely identified by its primary key, typically an auto-incrementing integer or UUID.
Item Structure An item consists of field-value pairs corresponding to the collection’s schema:
{ "id" : 1 , "title" : "Introduction to Directus" , "content" : "Directus is a powerful headless CMS..." , "status" : "published" , "author" : 5 , "date_created" : "2024-03-01T10:30:00Z" , "date_updated" : "2024-03-03T15:45:00Z" }
Creating Items Items are created through the API by providing field values:
POST /items/articles Content-Type : application/json { "title" : "Getting Started with Directus" , "content" : "This guide will help you..." , "status" : "draft" , "author" : 5 }
From the source code (~/workspace/source/api/src/services/items.ts:126-169), the creation process:
Validates the payload against permissions
Runs pre-create hooks for modifications
Processes presets from permissions
Handles Many-to-One (M2O) relationships
Handles Any-to-One (A2O) relationships
Inserts the record into the database
Processes One-to-Many (O2M) relationships
Returns the primary key of the new item
Auto-Generated Fields Certain fields are automatically populated:
Primary Key : Auto-incremented unless manually specifieduser_createddate_createdDefault Values : Applied from field schema
// From ~/workspace/source/api/src/services/items.ts:223-224 const primaryKey : undefined | PrimaryKey = payloadWithTypeCasting [ primaryKeyField ]; if ( primaryKey ) { validateKeys ( this . schema , this . collection , primaryKeyField , primaryKey ); }
Reading Items Get All Items Returns a list of all items in the collection (subject to permissions).
Get Single Item Retrieve a specific item by its primary key.
Query Parameters Directus provides powerful query parameters for filtering, sorting, and pagination:
GET /items/articles?filter[status][_eq]=published&sort=-date_created&limit=10&offset=20
Filtering { "filter" : { "status" : { "_eq" : "published" }, "author" : { "_eq" : 5 }, "date_created" : { "_gte" : "2024-01-01" } } }
Field Selection GET /items/articles?fields=id,title,author.first_name,author.last_name
Supports nested field selection through relationships using dot notation.
Sorting GET /items/articles?sort=title,-date_created
Prefix with - for descending order.
GET /items/articles?limit=25&page=2
Or use offset-based pagination:
GET /items/articles?limit=25&offset=50
Search GET /items/articles?search=directus
Searches across all searchable fields in the collection.
Updating Items Update Single Item PATCH /items/articles/1 Content-Type : application/json { "status" : "published" , "published_date" : "2024-03-03" }
Update Multiple Items Update multiple items by their IDs:
PATCH /items/articles Content-Type : application/json { "keys" : [ 1 , 2 , 3 ], "data" : { "status" : "archived" } }
Or update by query:
PATCH /items/articles?filter[status][_eq]=draft Content-Type : application/json { "status" : "published" }
Auto-Updated Fields
user_updateddate_updated
Deleting Items Delete Single Item Delete Multiple Items DELETE /items/articles?filter[status][_eq]=draft
Or by IDs:
DELETE /items/articles/1,2,3
Deleting items is permanent unless you have revisions enabled. Always ensure you have backups before bulk deletions.
Item Revisions When revisions are enabled for a collection, Directus tracks every change to items:
{ "collection" : "articles" , "meta" : { "versioning" : true } }
Each change creates a revision record in directus_revisions:
{ "id" : 123 , "collection" : "articles" , "item" : "1" , "data" : { "title" : "Updated Title" }, "delta" : { "title" : "Original Title" }, "activity" : 456 }
You can revert to previous revisions through the API or app interface.
Item Activity When accountability is enabled, all item actions are logged in directus_activity:
{ "id" : 789 , "action" : "update" , "user" : 5 , "timestamp" : "2024-03-03T15:45:00Z" , "collection" : "articles" , "item" : "1" , "comment" : null }
Activities include:
create - Item creationupdate - Item modificationdelete - Item deletioncomment - Comments added to item
Nested Relational Data Items can include related data from other collections through field expansion:
GET /items/articles/1?fields=*,author.*,categories.*
Response includes full related objects:
{ "id" : 1 , "title" : "Introduction to Directus" , "author" : { "id" : 5 , "first_name" : "John" , "last_name" : "Doe" , "email" : "[email protected] " }, "categories" : [ { "id" : 10 , "name" : "Tutorials" }, { "id" : 12 , "name" : "Getting Started" } ] }
Deep Nesting Supports deep nesting of relationships:
GET /items/articles?fields=*,author.role.*,author.avatar.*
Creating Items with Relationships Create related items inline during item creation:
{ "title" : "New Article" , "author" : { "first_name" : "Jane" , "last_name" : "Smith" , "email" : "[email protected] " }, "categories" : [ { "categories_id" : 10 }, { "categories_id" : { "name" : "New Category" } } ] }
From the source code (~/workspace/source/api/src/services/items.ts:203-216), relationship processing handles:
M2O (Many-to-One) : Creates related item first, uses returned IDA2O (Any-to-One) : Similar to M2O with collection specificationO2M (One-to-Many) : Creates child items after parent, linking via foreign key
Batch Operations Directus supports efficient batch operations:
Create Multiple Items POST /items/articles Content-Type : application/json [ { "title" : "Article 1" , "status" : "draft" }, { "title" : "Article 2" , "status" : "draft" }, { "title" : "Article 3" , "status" : "draft" } ]
Update Multiple Items PATCH /items/articles Content-Type : application/json [ { "id" : 1 , "status" : "published" }, { "id" : 2 , "status" : "published" }, { "id" : 3 , "status" : "archived" } ]
Batch mutations have a configurable limit (default 25,000 mutations) to prevent performance issues.
From the source code (~/workspace/source/api/src/services/items.ts:89-104):
createMutationTracker ( initialCount = 0 ): MutationTracker { const maxCount = Number ( env [ 'MAX_BATCH_MUTATION' ]); let mutationCount = initialCount ; return { trackMutations ( count : number ) { mutationCount += count ; if ( mutationCount > maxCount ) { throw new InvalidPayloadError ({ reason: `Exceeded max batch mutation limit of ${ maxCount } ` }); } } }; }
Singleton Items For singleton collections, use a simplified API:
GET /items/settings PATCH /items/settings
No ID needed since only one item exists.
Common Use Cases
Content Publishing Create, edit, and publish blog posts, articles, and pages with draft/published workflows.
Product Catalogs Manage e-commerce products with variants, pricing, inventory, and categorization.
User Profiles Store user information, preferences, and settings with custom profile data.
Asset Metadata Enrich media files with tags, descriptions, credits, and licensing information.
Best Practices Use Transactions : For complex operations involving multiple items or collections, leverage database transactions for atomicity.
Batch Operations : When creating or updating multiple items, use batch endpoints instead of individual requests.
Field Selection : Only request the fields you need to reduce response payload size and improve performance.
Enable Revisions : For important content collections, enable revisions to track changes and allow rollbacks.
Optimize Queries : Use filters, limits, and indexes appropriately to ensure fast query performance.