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.

Example
/:project/items/:collection
/:project/activity
/system/info

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.

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

Click here for the full list of error codes.


Endpoints

Items

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

Open items reference

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

Open files reference

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

Open activity reference

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

Open collections reference

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

Open collection presets reference

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

Open extensions reference

Endpoints
   GET /interfaces
   GET /layouts
   GET /modules

Fields

Fields are individual pieces of content within an item. They are mapped to columns in the database.

Open field reference

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

Open folders reference

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

Open GraphQL reference

Endpoints
  POST /:project/gql

Mail

Send electronic mail through the electronic post.

Open mail reference

Endpoints
  POST /:project/mail

Permissions

Permissions control who has access to what and when.

Open permissions reference

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

Open projects reference

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

Open relations reference

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

Open revisions reference

Endpoints
   GET /:project/revisions
   GET /:project/revisions/:id

Roles

Roles are groups of users that share permissions.

Open roles reference

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

Open SCIM reference

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

Open server reference

Endpoints
   GET /server/info
   GET /server/ping

Settings

Settings control the way the platform works and acts.

Open settings reference

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

Open users reference

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

Open utilities reference

Endpoints
  POST /:project/utils/hash
  POST /:project/utils/hash/match
  POST /:project/utils/random/string
   GET /:project/utils/2fa_secret