/:project/items/:collection
/:project/activity
/system/info
Legacy Version
These are the docs for Directus 8, a legacy version of the platform. If you're looking for the current Directus 9 documentation, go here: https://docs.directus.io
API Reference
Directus offers both a RESTful and GraphQL API to manage the data in the database. The API has predictable resource-oriented URLs, relies on standard HTTP status codes, and uses JSON for input and output.
The input/output of the API differs greatly for individual installs, as most of the endpoints will return data that's based on your specific schema.
New to Directus?
See our Getting Started guide if this is your first time working with Directus.
Projects
Directus supports multi-tenancy out of the box. In order to do this, most endpoints will be prefixed with a project key based on the configuration filename.
When installing Directus for the first time, you'll be asked to provide a project key for your project. This is the project key that Directus expects in endpoints that require the project attribute.
Authentication
By default, all data in the system is off limits for unauthenticated users. To gain access to protected data, you must include an access token with every request.
You pass the token in either the Authorization header, or a query parameter:
Authorization: bearer t0k3n
?access_token=t0k3n
To learn more, checkout the authentication reference.
POST /:project/auth/authenticate
POST /:project/auth/refresh
POST /:project/auth/password/request
POST /:project/auth/password/reset
GET /:project/auth/sso
GET /:project/auth/sso/:provider
GET /:project/auth/sso/:provider/callback
Errors
Directus relies on standard HTTP status code to indicate the status of a request. Next to that, the API uses numeric codes to avoid the need for translated error messages based on locale. The error property is only present when an error has occurred.
Endpoints
Items
Items are individual pieces of data in your database. They can be anything, from articles, to IoT status checks.
GET /:project/items/:collection
GET /:project/items/:collection/:id
POST /:project/items/:collection
PATCH /:project/items/:collection/:id
DELETE /:project/items/:collection/:id
GET /:project/items/:collection/:id/revisions
GET /:project/items/:collection/:id/revisions/:offset
PATCH /:project/items/:collection/:id/revert/:revision
Files
Files can be saved in any given location. Directus has a powerful assets endpoint that can be used to generate thumbnails for images on the fly.
GET /:project/files
GET /:project/files/:id
POST /:project/files
PATCH /:project/files/:id
DELETE /:project/files/:id
GET /:project/files/:id/revisions
GET /:project/files/:id/revisions/:offset
PATCH /:project/files/:id/revert/:revision
Activity
All events that happen within Directus are tracked and stored in the activities collection. This gives you full accountability over everything that happens.
GET /:project/activity
GET /:project/activity/:id
POST /:project/activity/comment
PATCH /:project/activity/comment/:id
DELETE /:project/activity/comment/:id
Collections
Collections are the individual collections of items, similar to tables in a database.
Changes to collections will alter the schema of the database.
GET /:project/collections
GET /:project/collections/:collection
POST /:project/collections
PATCH /:project/collections/:collection
DELETE /:project/collections/:collection
Collection Presets
Collection presets hold the preferences of individual users of the platform. This allows Directus to show and maintain custom item listings for users of the app.
GET /:project/collection_presets
GET /:project/collection_presets/:id
POST /:project/collection_presets
PATCH /:project/collection_presets/:id
DELETE /:project/collection_presets/:id
Extensions
Directus can easily be extended through the addition of several types of extensions, including layouts, interfaces, and modules.
GET /interfaces
GET /layouts
GET /modules
Fields
Fields are individual pieces of content within an item. They are mapped to columns in the database.
GET /:project/fields
GET /:project/fields/:collection
GET /:project/fields/:collection/:field
POST /:project/fields/:collection
PATCH /:project/fields/:collection/:field
DELETE /:project/fields/:collection/:field
Folders
Folders don't do anything yet, but will be used in the (near) future to be able to group files.
GET /:project/folders
GET /:project/folders/:id
POST /:project/folders
PATCH /:project/folders/:id
DELETE /:project/folders/:id
GraphQL
GraphQL provides a complete description of the data in your API, giving you the power to ask for exactly what you need, and nothing more.
POST /:project/gql
Send electronic mail through the electronic post.
POST /:project/mail
Permissions
Permissions control who has access to what and when.
GET /:project/permissions
GET /:project/permissions/:id
GET /:project/permissions/me
GET /:project/permissions/me/:collection
POST /:project/permissions
PATCH /:project/permissions/:id
DELETE /:project/permissions/:id
Projects
Projects are the individual tenants of the platform. Each project has its own database and data.
GET /:project
GET /server/projects
POST /server/projects
DELETE /server/projects/:project
Relations
What data is linked to what other data. Allows you to assign authors to articles, products to sales, and whatever other structures you can think of.
GET /:project/relations
GET /:project/relations/:id
POST /:project/relations
PATCH /:project/relations/:id
DELETE /:project/relations/:id
Revisions
Revisions are individual changes to items made. Directus keeps track of changes made, so you're able to revert to a previous state at will.
GET /:project/revisions
GET /:project/revisions/:id
Roles
Roles are groups of users that share permissions.
GET /:project/roles
GET /:project/roles/:id
POST /:project/roles
PATCH /:project/roles/:id
DELETE /:project/roles/:id
SCIM
Directus partially supports Version 2 of System for Cross-domain Identity Management (SCIM). It is an open standard that allows for the exchange of user information between systems, therefore allowing users to be externally managed using the endpoints described below.
POST /:project/scim/v2/Users
GET /:project/scim/v2/Users
GET /:project/scim/v2/Users/:id
PATCH /:project/scim/v2/Users/:id
GET /:project/scim/v2/Groups
GET /:project/scim/v2/Groups/:id
PATCH /:project/scim/v2/Groups/:id
DELETE /:project/scim/v2/Groups/:id
Server
Access to where Directus runs. Allows you to make sure your server has everything needed to run the platform, and check what kind of latency we're dealing with.
GET /server/info
GET /server/ping
Settings
Settings control the way the platform works and acts.
GET /:project/settings
GET /:project/settings/:id
POST /:project/settings
PATCH /:project/settings/:id
DELETE /:project/settings/:id
Users
Users are what gives you access to the data.
GET /:project/users
GET /:project/users/:id
GET /:project/users/me
POST /:project/users
PATCH /:project/users/:id
DELETE /:project/users/:id
POST /:project/users/invite
POST /:project/users/invite/:token
PATCH /:project/users/:id/tracking/page
GET /:project/users/:id/revisions
GET /:project/users/:id/revisions/:offset
Utilities
Directus comes with various utility endpoints you can use to simplify your development flow.
POST /:project/utils/hash
POST /:project/utils/hash/match
POST /:project/utils/random/string
GET /:project/utils/2fa_secret