The Directus API is a quick and easy way to add a RESTful API layer to a new or existing SQL database. It perfectly mirrors the database architecture which allows for flexible content modeling and dynamic endpoints even when changing the schema or data directly. Below is a comprehensive reference of each endpoint and parameter alongside helpful examples that showcase typical request and response formats.

The Directus API uses SemVer for version labeling within the repo and for files which mention a specific version (eg: package.json). The API will not include the version in the URL because the API is "versionless". Being versionless means that existing API behavior will not be removed or changed, only new features and enhancements will be added. Therefore, no breaking changes will ever be introduced and you can safely keep your APIs up-to-date.

All endpoints are prefixed with a project key based on the configuration file name. The API will attempt to find a configuration file that matches the provided project key and use its settings. The underscore (_) is reserved as the default project key.

Below are few examples of API requests when your API is located in the root directory:

Data Type – The API checks the submitted value's type against the Directus or database's field type. For example, a String submitted for an INT field will result in an error.

RegEx – The API checks the submitted value against its column's directus_fields.validation PCRE RegEx pattern (must include delimiters). If the value doesn't match then an error will be returned. Read more about PCRE patterns and delimiters.

Most endpoints are checked against permissions. If a user is not authenticated or isn’t allowed to access certain endpoints then the API will respond with either a 401 Unauthorized or a 403 Forbidden respectively. In addition to these status codes, the API returns a specific reason in the error.message field.

For security reasons Apache hides the Authorization header to prevent other scripts from seeing the credentials used to access the server. Make sure your Apache is passing the Authentication header. Read more

The API checks the validity of the reset token, that it hasn't expired, and that the email address contained in the token payload matches one in the database. It uses a GET request so users can access it from links within their email clients. This endpoint generates a random password for the user and sends it to their email address.

fields is a CSV of columns to include in the result. This parameter supports dot notation to request nested relational fields. You can also use a wildcard (*) to include all fields at a specific depth.

# Get all top-level fields
?fields=*
# Get all top-level fields and all second-level relational fields
?fields=*.*
# Get all top-level fields and second-level relational fields within images
?fields=*,images.*
# Get only the first_name and last_name fields
?fields=first_name,last_name
# Get all top-level and second-level relational fields, and third-level fields within images.thumbnails
?fields=*.*,images.thumbnails.*

sort is a CSV of fields used to sort the fetched items. Sorting defaults to ascending (ASC) order but a minus sign (-) can be used to reverse this to descending (DESC) order. Fields are prioritized by their order in the CSV. You can also use a ? to sort randomly.

# Sorts randomly
?sort=?
# Sorts by name ASC
?sort=name
# Sorts by name ASC, followed by age DESC
?&sort=name,-age
# Sorts by name ASC, followed by age DESC, followed by random sorting
?sort=name,-age,?

Used to search items in a collection that matche the filter's conditions. Filters follow the syntax filter[<field-name>][<operator>]=<value>. The field-name supports dot-notation to filter on nested relational fields.

The format for date is YYYY-MM-DD and for datetime is YYYY-MM-DD HH:MM:SS. This formats translate to 2018-08-29 14:51:22.

Year in 4 digits

Months, days, minutes and seconds in two digits, adding leading zero padding when it's a one digit month

Hour in 24 hour format

@TODO: Implemented soon

Alias for current datetime now and current date today.

# Equals to
GET /items/comments?filter[datetime]=2018-05-21 15:48:03
# Greater than
GET /items/comments?filter[datetime][gt]=2018-05-21 15:48:03
# Greater than or equal to
GET /items/comments?filter[datetime][gte]=2018-05-21 15:48:03
# Less than
GET /items/comments?filter[datetime][lt]=2018-05-21 15:48:03
# Less than or equal to
GET /items/comments?filter[datetime][lte]=2018-05-21 15:48:03
# Between two date
GET /items/comments?filter[datetime][lte]=2018-05-21 15:48:03,2018-05-21 15:49:03

The lang parameter is a CSV of languages that should be returned with the response. This parameter can only be used when a Translation field has been included in the collection. This parameter supports the wildcard (*) to return all language translations.

The q parameter allows you to perform a search on all string and number type fields within a collection. It's an easy way to search for an item without creating complex field filters – though it is far less optimized. It only searches the root item's fields, related item fields are not included.

Items are essentially individual database records which each contain one or more fields (database columns). Each item belongs to a specific collection (database table) and is identified by the value of its primary key field. In this section we describe the different ways you can manage items.

This endpoint is dedicated to all user-defined collections only. Accessing system tables is forbidden. See Systems Endpoints for more information.

Get a specific revision of an item. This endpoint uses a zero-based offset to select a revision, where 0 is the creation revision. Negative offsets are allowed, and select as if 0 is the current revision.

All system tables (directus_*) are blocked from being used through the regular /items endpoint to prevent security leaks or because they require additional processing before sending to the end user. This means that any requests to /items/directus_* will always return 401 Unauthorized.

These system endpoints still follow the same spec as a “regular” /items/[collection-name] endpoint but require the additional processing outlined below:

The datatype (database vendor specific) may also be required if the type supports different datatypes. For example, the primary_key type supports both string and number, so it is also required to set the datatype to a numeric or string datatype.

When type requires a length, such as a string or integer, a length attribute is required.

{"collection":"projects","item_name_template":null,"managed":true,"hidden":false,"single":false,"translation":null,"note":"This collection will store all of our projects","icon":null,"fields":[{"field":"id","type":"integer","datatype":"int","interface":"primary_key","primary_key":true,"auto_increment":true,"length":10,"signed":false},{"field":"title","type":"string","datatype":"varchar","interface":"text-input","length":255,"readonly":false,"required":true,"note":"The project title"}]}

You must ensure that the Directus field type, database datatype, and interface all work together. This is easy when done through the App, since options are limited and defaults are provided. When working directly with the API you'll need to check compatibility.

For example, you wouldn't have a wysiwyg interface with a boolean type save to a datetime datatype... that's just crazy.

Directus is also compatible with System for Cross-domain Identity Management (SCIM) protocol. All roles have an external_id to link each with the external system, these must be unique within Directus. Directus will automatically generate a UUID (v4) if this field is left blank when creating a role.

Instead of deleting a user, you should instead soft-delete them (update their status to "suspended" or "deleted") to maintain accountability relations with the directus_users.id. Only hard-delete if the user was created in error and never used.

WARNING

Batch Delete can quickly destroy large amounts of data. Please be careful when implementing this request.

Sets the last accessed page/datetime of the Directus App. This information is used to determine if the user is still logged into the Directus App and to warn when multiple users are editing the same item.

Directus can easily be extended through the addition of several types of extensions. Extensions are and important part of the Directus App that live within the decoupled Directus API. These extensions include: Interfaces, Layouts, and Pages. These three different types of extensions live in their own directory and may have their own endpoints. All custom endpoints defined in extensions (pages, interfaces, etc) require authentication.

Webhooks allow you to send an HTTP request when a specific event occurs. Creating a webhook in Directus is done by creating a custom hook that makes an HTTP request.

The example below sends a POST request to http://example.com/alert every time an article is created, using the following payload:

{"type":"article","data":{"title":"new article","body":"this is a new article"}}

<?phpreturn['actions'=>[// Send an alert when a article is created'collection.insert.articles'=>function(array$data){$client=new\GuzzleHttp\Client(['base_uri'=>'http://example.com']);$data=['type'=>'article','data'=>$data];$response=$client->request('POST','/alert',['json'=>$data]);}]];

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.