menuclose
Introduction

The Directus API v1.1

Connect your data with our RESTful API and SDKs

Access to your instance's data is simple. Authenticate with a user's access token and the API inherits all of their system privileges.

It is important to remember that the Directus API is dynamic based on your database schema/architecture. That means that if you change a column or table name, the respective API endpoints will also change. So if you adjust your schema it is important to update any existing endpoints in your application code.

Note: We recommend encrypting all Directus traffic over HTTPS

Note: The Directus Hosted Service encrypts all traffic over HTTPS

Other Versions

The older version (1.0) of the Directus API is available below.

http://api.getdirectus.com/1.0/

Error Responses

Not Authenticated

You must be logged in to Directus to access the API. Some high-level view permissions (ex. table-listing) are not strictly enforced by privileges, just general authentication.

Parse

Any non-JSON response: Error

Custom Endpoints

To add custom endpoints into Directus, simply create new sandboxed endpoints using Slim routes for any custom files.

Translations & Locales

@TODO

Authentication

Authentication privileges are inherited from the user-group that the key was generated from.

API Key

A single consumer-key is generated for each user which is passed as a parameter with every API resource that uses this type. Used with all GET Resources

Authentication is performed by using your private account API Key. You can generate API keys here. @TODO

Authentication can be done in three different ways:

Request API Key

Using a user's credentials you can get its API token key by sending a POST request to /api/1.1/auth/request-token.

curl -d "email=user@directus.local&password=pass123" https://instance--key.directus.io/api/1.1/auth/request-token

On a successful request the API will respond with the json below:

{
  "success": true,
  "data": {
    "token": "userAPIToken"
  }
}

Otherwise with the json below:

{
  "success": false,
  "error": {
    "message": "Incorrect email or password"
  }
}

HTTP Basic Auth

curl -u Py8RumuLD7HE5juFrOR5: https://instance--key.directus.io/api/1.1/tables

Pay attention to the colon after the API key, it's not part of the API key.

Bearer Auth

Instead of using -u Py8RumuLD7HE5juFrOR5: it can be used Authentication header.

curl -H "Authorization: Bearer Py8RumuLD7HE5juFrOR5" https://instance--key.directus.io/api/1.1/tables

Query String

curl https://instance--key.directus.io/api/1.1/tables?access_token=Py8RumuLD7HE5juFrOR5

Security

All API calls pass through ACL

Passwords

Directus using the CRYPT_BLOWFISH algorithm generates random salts when a password is hashed, encodes the hash-type, salt and stretching iteration count into the “hash encoding string”. During the comparison, it reads this string to retrieve necessary information.

Database Security

Timing Attacks

While account email probing is theoretically possible, you can dummy salt so there is a consistent response time if desired.

Password Reset

When a new password is requested, the existing password is NULLIFIED and a new unique password token is sent to the account's email address.

XSS

While internal XSS may be possible, successfully authenticated users are assumed to be non-malicious. This was a design decision to give full control to any connected applications. All malicious data needs to be sanitized in the web-application/data entry point, else the database and therefore Directus could become compromised.

Session Hijacking

Currently, nothing is done to minimize potential attacks via session hijacking. One possible advancement would be to validate the session with request metadata to provide partial security.

API Endpoints

Base API URL: {{DIRECTUS_ROOT}}/api/1.1/

Activity

Type Resource Description
GET /activity Collection of latest Directus activity

Authentication

Type Resource Description
POST /auth/request-token Gets your user token using your credentials

Bookmarks

Type Resource Description
POST /bookmarks Create new link in the sidebar
GET /bookmarks All the bookmarks
GET /bookmarks/self Bookmarks for currently authenticated user
GET /bookmarks/[id] Details for a specific bookmark
DELETE /bookmarks/[id] Deletes a Bookmarks with the given id

Columns

Type Resource Description
POST /tables/[table-name]/columns Creates a new column in the given table
GET /tables/table-name/columns Collection of the column details for a given table
GET /tables/table-name/columns/column-name Details for a specific column in a given table
DELETE /tables/[table-name]/columns/[column-name] Deletes a given column
PUT /tables/[table-name]/columns/[column-name] Updates the given column

Files

Type Resource Description
POST /files Creates a new file
GET /files/[id] Retrieves details for a specific file
GET /files Retrieves a collection of files
PUT /files/[id] Updates the details for a specific file

Groups

Type Resource Description
POST /groups Creates a new group
GET /groups Retrieves a collection of all Directus user-groups
GET /groups/[id] Retrieves details for a specific user-group

Items

Type Resource Description
POST /tables/[table-name]/rows Creates a new item in the given table
GET /tables/[table-name]/rows Retrieves a collection of rows (items) for a given table
GET /tables/[table-name]/rows/id Retrieves details for a specific table row (item)
PUT /tables/[table-name]/rows/[row-id] Updates an item within a specific table
DELETE /tables/[table-name]/rows/[row-id] Delete (or soft-delete) an item within a specific table

Messages

Type Resource Description
GET /messages/rows Retrieves a collection of messages for the authenticated user
GET /messages/rows/[id] Retreives details for a specific message

Preferences

Type Resource Description
GET /preferences/table-name Retrieves preferences for a specific table or bookmark
PUT /tables/[table-name]/preferences Update a preference within a specific table

Privileges

Type Resource Description
POST /privileges/[group-id] Creates new table privileges for the specified user group
GET /privileges/[group-id] Retrieves privileges for a given user-group
GET /privileges/[group-id]/[table-name] Gets the table privileges for a specific user group
PUT /privileges/[group-id]/[privileges-id] Updates the specified group privileges for the specified table

Settings

Type Resource Description
GET /settings Gets Directus Settings (Admin)
GET /settings/[collection-name] Gets Directus Settings (Admin) in the given collection
PUT /settings/[collection-name] Updates or Create settings in the given collection

Tables

Type Resource Description
POST /tables Creates a new table within the database
GET /tables Collection of tables viewable by current user
GET /tables/[table-name] Gets system and schema information for a specific table

Global Parameters

Name Value Description
limit Integer Default 200 The number of items to request
offset Integer Default 0 The offset for for the items
order[field] String Default ASC Order to be sorted. Available options are: ASC (Ascending) or DESC (Descending)
status String Default None List of status values to be included. Separated by commas. 1,2
columns String Optional The columns to be shown on the result. Columns are separated by comma. columns=id,title,published_date
in[field] String Optional Only list records that its field matches one of given value. Can be separated by commas. in[id]=1,2
ids String Optional Only list records that its field matches one of given value. Can be separated by commas. ids=1,2. Same as in[id]=1,2
skip_activity_log Default 0 Whether or not the update is going to be logged in activity
filters Optional Use the operators below to filter the result: Filter Operators

Filter Operators

Filter the request by using any of the supported operators.

Operator Description
=, eq, None Equal to
<>, !=, neq Not Equal to
<, lt Less than
<=, lte Less than or equal to
>, gt Greater than
>=, gte Greater than or equal to
in Match one of the value in the list
nin Not match any value in the list
null Is Null
nnull Is Not Null
contains, like Contains a string
ncontains, nlike Not Contains a string
between Is Between
nbetween Is Not Between
empty Is Empty (NULL or empty string)
nempty Is Not Empty (NULL or empty string)
all Match all related items
has Has one or more related items

Example API Requests

GET /api/1.1/tables/[table-name]/rows

Retrieve a collection of items within a specific table based on the current user's privileges

Name Value Description
table-name String The table name you wish to get items from

Example Request

$ curl -g https://instance--key.directus.io/api/1.1/tables/directus_users/rows?filters[email][like]=@rngr.org \
        -u [user-token]:
$users = $client->getItems('directus_users, [
  'filters' => ['email' => ['like' => '@rngr.org']]
]);

Response

User Object

Example Response

{
  "meta": {
    "table": "directus_users",
    "type": "collection",
    "total": 1,
    "Active": 9,
    "Delete": 0,
    "Draft": 0,
    "total_entries": 9
  },
  "data": [
  {
      "id": 1,
      "active": 1,
      "first_name": "Ben",
      "last_name": "Haynes",
      "email": "ben@rngr.org",
      "token": "user-token",
      "position": "",
      "email_messages": 1,
      "last_login": "2016-12-02T07:44:45-04:00",
      "last_access": "2016-12-02T07:44:45-04:00",
      "last_page": "",
      "ip": "",
      "group": {
        "meta": {
          "table": "directus_groups",
          "type": "item"
        },
        "data": {
          "id": 1,
          "name": "Administrator",
          "description": null,
          "restrict_to_ip_whitelist": "0"
        }
      },
      "avatar": "//www.gravatar.com/avatar/65abcdof6a5aea481d9124343433423sab97e0a0fe?s=200&d=identicon&r=g",
      "avatar_file_id": null,
      "location": "",
      "phone": "",
      "address": "",
      "city": "",
      "state": "",
      "zip": "",
      "language": "en",
      "timezone": "America/New_York"
    },
    {
      "id": 2,
      "active": 1,
      "first_name": "Welling",
      "last_name": "Guzmán",
      "email": "welling@rngr.org",
      "token": "user-token",
      "position": "",
      "email_messages": 1,
      "last_login": "2016-11-02T07:44:45-04:00",
      "last_access": "2016-11-02T07:44:45-04:00",
      "last_page": "",
      "ip": "",
      "group": {
        "meta": {
          "table": "directus_groups",
          "type": "item"
        },
        "data": {
          "id": 1,
          "name": "Administrator",
          "description": null,
          "restrict_to_ip_whitelist": "0"
        }
      },
      "avatar": "//www.gravatar.com/avatar/653cc7f6a5aea481d9124343433423sab97e0a0fe?s=200&d=identicon&r=g",
      "avatar_file_id": null,
      "location": "",
      "phone": "",
      "address": "",
      "city": "",
      "state": "",
      "zip": "",
      "language": "es",
      "timezone": "Pacific/Midway"
    }
  ]
}

GET /api/1.1/tables/[table-name]/rows

Returns a collection of table entries based on the current user's privileges

Name Value Description
table-name String The table name you wish to get items from
limit Integer Default 200 The number of items to request
offset Integer Default 0 The offset for for the items
order[field] String Default ASC Order to be sorted. Available options are: ASC (Ascending) or DESC (Descending)
status String Default None List of status values to be included. Separated by commas, eg: 1,2
columns String Optional The columns to be shown on the result. Columns are separated by comma. columns=id,title,published_date
in[field] sting Optional Only list records that its field matches one of given value. Can be separated by commas, eg: in[id]=1,2
ids Optional Comma delimited list of ids to return

Example Request

$ curl https://instance--key.directus.io/api/1.1/tables/directus_users/rows \
        -u [user-token]:
$projects = $client->getItems('users');

Example Response

{
  "meta": {
    "active": 1,
    "inactive": 0,
    "trash": 0,
    "total": 1,
    "type": "collection",
    "table": "directus_users"
  },
  "data": [
    {
      "id": 3,
      "active": 1,
      "first_name": "John",
      "last_name": "Smith",
      "email": "john.smith@example.com",
      "password": "asfafspojd92en1oi2n31b412ubb1n",
      "salt": "5329e597d9afa",
      "position": "",
      "email_messages": 1,
      "last_login": null,
      "last_access": null,
      "last_page": "",
      "ip": "",
      "group": {
            "id": 0,
            "name": "Administrator",
            "description": null,
            "restrict_to_ip_whitelist": 0
      },
      "avatar": null,
      "location": "",
      "phone": "",
      "address": "",
      "city": "",
      "state": "",
      "zip": ""
    }
  ]
}

Filters

Filters are a way to refine listing results based on one or more conditions.

How to use

To add a filter you have to use the query param key filters with the following format: filters[column-name][operator]=value

Example: Fetching customers from United States

api/1.1/tables/customers/rows?filters[country][eq]=us

api/1.1/tables/customers/rows is the endpoint where all the rows are returned, limited by the default limit, which is 200.

filters[country][eq]=us filters the customers to only those with country equal to us.

Also filters[country][eq]=us can be simplified to filters[country]=us

To add another filter you have to separate each filters with the ampersand symbol (&).

Example: Fetching customers from New York, United States

api/1.1/tables/customers/rows?filters[country][eq]=us&filters[state][eq]=ny

Example: Fetching customers from New York and New Mexico, United States

api/1.1/tables/customers/rows?filters[country][eq]=us&filters[state][in]=ny,nm

By default all condition are grouped in AND logical operators, the example below will explain how to use or operator:

Example: Fetching customers from New York and New Mexico OR Oregon and Louisiana, United States

api/1.1/tables/customers/rows?filters[country][eq]=us&filters[state][in]=ny,nm&filters[state][logical]=or&filters[state][in]=or,la

Note: Directus does not support relational filtering or multiple filters for the same column (yet).

Supported Operators

Operator Description
=, eq Equal to
<>, !=, neq Not Equal to
<, lt Less than
<=, lte Less than or equal to
>, gt Greater than
>=, gte Greater than or equal to
in Match one of the value in the list
nin Not match any value in the list
null Is Null
nnull Is Not Null
contains Contains a string
ncontains Not Contains a string
between Is Between
empty Is Emtpy
nempty Is Not Empty
has Has one or more related entries

Directus Objects

These are the Directus object models used throughout the system.

Meta Object

Attribute Description
type String Whether the data returned is a collection or a single item
table String Table the data was fetched from
Active Integer How many active items has this table
Draft Integer How many draft items has this table
Delete String How many deleted items has this table
total String How many items were returned
total_entries String How many items the table has

The status name are configurable and Active, Draft and Delete are the default values.

Activity Object

Attribute Description
id Integer Activity Unique Identification number
type String Activity Type: ENTRY, UI, FILES, SETTINGS, UI, LOGIN and MESSAGES @TODO: Clarification
action String Activity Action: ADD, UPDATE, DELETE and LOGIN
identifier String The record identifier
row_id Integer The record/item primary key (ID)
user Integer ID of the users that performed the action
data String Data used on the action in json
delta String The difference in the new and old data in json
parent_id Integer ID of the parent record/item, if the current record/item is relational
parent_table String ID of the parent record/item table
parent_changed Boolean Whether or not the parent record/item changed along with its child
datetime String When the activity was performed (UTC Time)
logged_ip String User IP
user_agent String User user agent

Bookmark Object

Attribute Description
id Integer Bookmark Unique Identification number
user Integer [Directus user id] This assigns the bookmark to a specific user (there's a ticket to allow for "global" bookmarks using NULL)
title String The text to display in the navigation menu
url String The path to navigate to when clicked, relative to the Directus root
icon_class String Deprecated
active String Deprecated
section String ["search" or "other"] Which nav section to show the link within. User generated bookmarks use "search", while all system links go within "other"

Column Object

Attribute Description
id Integer Column Unique Identification number
table_name Integer The name of the table containing the column
column_name String The name of the column
data_type String The datatype of the column. Other database types (eg SQLite) have limited datatypes and this more granular value is used to know exactly how to format/type API responses. If you change the datatype directly in the database be sure to update this value. Some Directus fields are not actual columns (such as ONETOMANY), these are saved as an ALIAS and represent the ghost column
ui String This stores the current User-Interface ID
relationship_type String This column stores the relationship type (NULL if non-relational). As an ENUM there are three options: MANYTOONE, MANYTOMANY, ONETOMANY
related_table String Only for relational columns, this value holds the table containing the related data
junction_table String Only for MANYTOMANY relational columns, this value holds the junction/bridge/associative table name. This is the table that stores two foreign keys which link related items between two tables
junction_key_left String Only for MANYTOMANY relational columns, this value holds the column name (in the junction table) that stores "this" item's ID
junction_key_right String Only for relational columns, this value stores the column name that stores the "right" key: MANYTOMANY – The column name (in the junction table) that stores the related item's ID. MANYTOONE – The column name (in the this table) that stores the related item's ID. Should be the same value as column_name. ONETOMANY – The column name (in the related table) that stores this item's ID
hidden_input String [0,1] Whether or not this column's field will be hidden from all users. This is global and overrides any user group permissions
hidden_list String F[0,1] Whether or not this column's field on listing page will be hidden from all users. This is global and overrides any user group permissions
required String [0,1] Whether or not the field is required before saving the edit item page
sort String [1,2,3...] This stores the sort order for the Directus fields. This is based on the database column order but can be changed since column order is tied to lookup/optimizations and the CMS view shouldn't impact that. New items are stored with a 9999 until they are sorted with the drag-and-drop Settings interface
comment String This stores a note to be displayed beside the field on the edit page. This is based on the database column comment but has been decoupled since some database types (eg SQLite) don't natively support comments

File Object

Attribute Description
id Integer File Unique Identification number
active Integer File's status. 1=active, 2=inactive, 3=deleted
name String File name
title String File's title
location String Location of where the picture was taken. if any
type String File mime type
url String File url relativity to Directus base url
tags String Comma separated tags
caption String File caption (Description)
width Integer File width
height Integer File height
size Integer File size in bytes
embed_id String ID of the embeded file. Ex Youtube ID
user Integer File owner (who uploaded the file)
date_uploaded String File uploaded date. TODO It should be an DateTime object
storage_adapter String Storage adapter used to upload the file

Preference Object

Attribute Description
id Integer Preference's Unique Identification number
user Integer Preference owner. User ID
table_name String Name of the table
columns_visible String List of visible columns, separated by commas
sort String Result will be sorted by this column
sort_order String Sort Order. (ASC=Ascending or DESC=Descending)
status String List of status values. separated by comma

Privilege Object

Attribute Description
id Integer Privilege's Unique Identification number
group_id Integer Group ID
table_name String Table name that this permissions belongs to
allow_add Integer Whether the group is allow to add/create entries in the table (See values below)
allow_edit Integer Whether the group is allow to edit/update entries in the table (See values below)
allow_delete Integer Whether the group is allow to delete/remove entries in the table (See values below)
allow_view Integer Whether the group is allow to view/read entries in the table (See values below)
allow_alter Integer Whether the group is allow to add/create entries in the table (See values below)
nav_listed Boolean Whether the table should be visible in the sidebar
read_field_blacklist String List of columns that the group can't view/read
write_field_blacklist String List of columns that the group can't edit/update
status_id String State of the record that this permissions belongs to (Draft, Active or Soft Deleted)

Table Object

Attribute Description
table_name Integer Table Unique name.
hidden Boolean Determines if the table is completely hidden from Directus or not
single Boolean Determines if the table contains only one record/item or multiple. When Single tables are clicked in the sidebar, the Item Listing page is skipped, taking users directly to the Item Edit page. The lone item should have an id of 1
default_status Integer This is the table's default status value – which must be an option within the configuration file's Status Mapping
footer Boolean Determines if a table footer should be shown on the Item Listing page with helper functions for INT columns such as: Average, Min, Max, etc
list_view Boolean Allows for the Item Listing page to be overridden with a custom view template @TODO
column_groupings String Soon to be deprecated, this column was used to group columns on the Item Edit page
primary_column String Soon to be deprecated, This stores the column name that represents a table item/record
user_create_column String Optional. Enter the name of a column to store the Directus User ID that created the item
user_update_column Integer Optional. Enter the name of a column to store the datetime that the item was created
date_create_column Integer Optional. Enter the name of a column to store the Directus User ID that last modified the item
date_update_column Integer Optional. Enter the name of a column to store the datetime that the item was last modified
filter_column_blacklist String A CSV of column names in this table that should not be included in the Item Listing page's filter component

User Object

Attribute Description
id Integer User's Unique Identification number
active Integer User's status. 1=active, 2=inactive, 3=deleted
email String User's unique email address
first_name String User first name
last_name String User last name
password String hashed password
token String User's unique API access token
group Integer User's group ID
email_messages Boolean Whether the user wants to receive email notification
avatar String Avatar url
avatar_file_id Integer File id used as avatar
language String User's default language. Language Supported en (English), es (Spanish), de (German), fr (French), it (Italian), zh-hans (Simplified Chinese) and nl (Dutch)
timezone String User's default timezone
position String User's position on the project/company
location String User's location in the world or universe
phone String User's phone number
address String User's address
city String User's city
state String User's state
zip String User's zip code
Items

Create Item

Note: Table names are case-sensitive

Note: These arguments and attributes are based on the table's custom columns

POST /api/1.1/tables/[table-name]/rows

Create a new item within the specified table

Name Value Description
table String Required The table within which the item will be added
data Array This data and its architecture is based on your specific project's schema

Example Request

$ curl --data "active=1&title=Lorem+Ipsum" \
        https://instance--key.directus.io/api/1.1/tables/projects/rows \
                -u [user-token]:
$newProject = $client->createItem('projects', [
    'active' => 1,
    'title' =>  'Lorem Ipsum'
]);
client.createItem('projects', {
  active: 1,
  title: 'Lorem Ipsum'
});

Response

Attribute Description
meta object The Directus system metadata object that provides useful information not contained within the dataset itself Meta Object: View Nested Attributes
data object This data and its architecture is based on your specific project's schema

Example Response

{
  "meta": {
    "type": "item",
    "table": "projects"
  },
  "data": {
    "id": 1,
    "active": 1,
    "title": "Lorem Ipsum"
  }
}

Get Items

Note: Table names are case-sensitive

Note: These arguments and attributes are based on the table's custom columns

GET /api/1.1/tables/[table-name]/rows

Retrieve a collection of items within a specific table based on the current user's privileges

Name Value Description
table-name String Required The table you wish to get the items from
limit Integer Default 200 The number of items to request
offset Integer Default 0 The offset for for the items
order[field] String Default ASC Order the result will be sorted to. Available options are: ASC (Ascending) or DESC (Descending)
status String Default None List of status values to be included. Separated by commas: 1,2
columns String Optional The columns to be shown on the result. Columns are separated by comma: columns=id,title,published_date
in[field] sting Optional Only list records where the field matches a specific value. Values can be separated by commas: in[id]=1,2
ids Optional Only list records with the specified id values. Can be separated by commas. ids=1,2. Same as in[id]=1,2
filters Optional Use Filter Operators to filter the result

Example Request

$ curl https://instance--key.directus.io/api/1.1/tables/projects/rows \
        -u [user-token]:
$projects = $client->getItems('projects');
client.getItems('projects');

Response

Attribute Description
meta Meta Object The Directus system metadata object that provides useful information not contained within the dataset itself Meta Object: View Nested Attributes
data object This data and its architecture is based on your specific project's schema

Example Response

{
  "meta": {
    "Delete": 0,
    "Active": 1,
    "Draft": 0,
    "total": 1,
    "total_entries": 1,
  },
  "data": [
    {
      "id": 1,
      "title": "Lorem Ipsum"
    },
    {
      ...
    }
  ]
}

Get Item

Note: Table names are case-sensitive

GET /api/1.1/tables/[table-name]/rows/[row-id]

Get a specific item within a table

Name Value Description
table-name String Required The table that contains the item you wish to get
row-id Integer Required The id of the item you wish to get

Example Request

$ curl https://instance--key.directus.io/api/1.1/tables/projects/rows/1 \
        -u [user-token]:
$item = $client->getItem('projects', 1);
client.getItem('projects', 1);

Response

Attribute Description
meta Meta Object The Directus system metadata object that provides useful information not contained within the dataset itself Meta Object: View Nested Attributes
data object This data and its architecture is based on your specific project's schema

Example Response

{
  "meta": {
    "type": "item",
    "table": "projects"
  },
  "data": {
    "id": 1,
    "title": "Lorem Ipsum"
  }
}

Update Item

Note: Table names are case-sensitive

PUT /api/1.1/tables/[table-name]/rows/[row-id]

Update an item within a specific table

Name Value Description
table-name String Required The table that contains the item you wish to update
row-id Integer Required The id of the item you wish to update
Custom Data Array Required This data and its architecture is based on your specific project's schema

Example Request

$ curl --data "title=Lorem Ipsum" \
        https://instance--key.directus.io/api/1.1/tables/projects/rows/1 \
                -u [user-token]:
$updatedProject = $client->updateItem('projects', 1, [
  'title' => 'Lorem Ipsum'
]);
client.updateItem('projects', 1, {
  title: 'Lorem Ipsum'
});

Response

Attribute Description
meta Meta Object The Directus system metadata object that provides useful information not contained within the dataset itself Meta Object: View Nested Attributes
data object This data and its architecture is based on your specific project's schema

Example Response

{
  "meta": {
    "type": "item",
    "table": "projects"
  },
  "data": {
    "id": 1,
    "active": 1,
    "title": "Lorem Ipsum"
  }
}

Delete Item

Note: Table names are case-sensitive

Note: To perform a Soft-delete directly, use the update endpoint and update the active column

DELETE /api/1.1/tables/[table-name]/rows/[row-id]

Delete (or soft-delete) an item within a specific table

Name Value Description
table-name String Required The table that contains the item you wish to delete
row-id Integer Required The id of the item you wish to delete

Example Request

$ curl -X DELETE \
        https://database.account.directus.io/api/1.1/tables/projects/rows/1 \
                -u [user-token]:
$response = $client->deleteItem('projects', 1);
client.deleteItem('projects', 1);

Response

Attribute Description
meta Meta Object The Directus system metadata object that provides useful information not contained within the dataset itself Meta Object: View Nested Attributes
success Boolean Whether the deletion was successful or not

Example Response

{
  "meta": {
    "table": "projects"
  },
  "success": true
}
Files

Create File

POST /api/1.1/files

Add a new file into the Directus File Library

Name Value Description
data Integer The file's Base64 content
active Integer The file's status, default options are: 1 (active), 2 (inactive), 0 (deleted)
name String The name used in the filesystem, including the extension, eg: "my-file.jpg". This is generated by the system based on Global Settings
title String The file's title
location String Location of where the picture was taken, if any. Pulled from the IPTC location when available
type String The file's mime type
tags String A CSV of tags for this file. Pulled from the IPTC keywords when available
caption String The file's caption or description. Pulled from the IPTC description when available

Example Request

$newFile = $client->createFile(new File([
  'path' => '/path/to/file.jpg',
  'title' => 'My File Name'
]));
client.createFile({
  title: 'My File Name',
  data: 'bm90aGluZyB0byBzZWUgaGVyZQ==' // Base64 file content
});

Response

Attribute Description
meta Meta Object The Directus system metadata object that provides useful information not contained within the dataset itself Meta Object: View Nested Attributes
data File Object This data and its architecture is based on the Directus file schema and can be extended with additional custom columns File Object: View Nested Attributes

Example Response

{
  "meta": {
    "table": "directus_files",
    "type": "item"
  },
  "data": {
    "id": 2,
    "active": 1,
    "name": "2a05d2300cf0a8bf1a3f6567366affed.jpg",
    "url": null,
    "title": "My File Name",
    "location": "",
    "caption": "",
    "type": "image\/jpg",
    "charset": "binary",
    "tags": "",
    "width": 594,
    "height": 447,
    "size": 52155,
    "embed_id": null,
    "user": 1,
    "date_uploaded": "2013-11-15 04:30:52 UTC",
    "storage_adapter": "local"
  }
}

Get Files

GET /api/1.1/files

Get all files within the Directus File Library

Name Value Description
id Integer Required The id of the file you wish to get
limit Integer Default 200 The number of items to request
offset Integer Default 0 The offset for for the items
order[field] String Default ASC Order to be sorted. Available options are: ASC (Ascending) or DESC (Descending)
status String Default None List of status values to be included. Separated by commas, eg: 1,2
columns String Optional The columns to be shown on the result. Columns are separated by comma, eg: columns=id,title,published_date
in[field] String Optional Only list records that its field matches one of given value. Can be separated by commas, eg: in[id]=1,2
ids String Optional Only list records that its field matches one of given value. Can be separated by commas. ids=1,2. Same as in[id]=1,2
filters Object Optional Use the Filter Operators to filter the result Filter Object

Example Request

$ curl https://instance--key.directus.io/api/1.1/files \
  -u [user-token]:
$files = $client->getFiles();
client.getFiles();

Response

Attribute Description
meta Meta Object The Directus system metadata object that provides useful information not contained within the dataset itself Meta Object: View Nested Attributes
data File Object Collection This data and its architecture is based on the Directus file schema and can be extended with additional custom columns File Object: View Nested Attributes

Example Response

{
  "meta": {
    "table": "directus_files",
    "type": "collection",
    "Active": 1,
    "Delete": 0,
    "Draft": 0,
    "total": 1,
    "total_entries": 1
  },
  "data": [{
    "id": 1,
    "active": 1,
    "name": "2a05d2300cf0a8bf1a3f6567366affed.jpg",
    "url": null,
    "title": "My File Name",
    "location": "",
    "caption": "",
    "type": "image\/jpg",
    "charset": "binary",
    "tags": "",
    "width": 594,
    "height": 447,
    "size": 52155,
    "embed_id": null,
    "user": 1,
    "date_uploaded": "2013-11-15 04:30:52 UTC",
    "storage_adapter": "local"
  }]
}

Get File

GET /api/1.1/files/[id]

Get a specific file (and its metadata) from within the Directus File Library

Name Value Description
id Integer Required The id of the file you wish to get

Example Request

$ curl https://instance--key.directus.io/api/1.1/files/1 \
  -u [user-token]:
$file = $client->getFile(1);
client.getFile(1);

Response

Attribute Description
meta Meta Object The Directus system metadata object that provides useful information not contained within the dataset itself Meta Object: View Nested Attributes
data File Object This data and its architecture is based on the Directus file schema and can be extended with additional custom columns File Object: View Nested Attributes

Example Response

{
  "meta": {
    "table": "directus_files",
    "type": "item"
  },
  "data": {
    "id": 1,
    "active": 1,
    "name": "2a05d2300cf0a8bf1a3f6567366affed.jpg",
    "url": null,
    "title": "My File Name",
    "location": "",
    "caption": "",
    "type": "image\/jpg",
    "charset": "binary",
    "tags": "",
    "width": 594,
    "height": 447,
    "size": 52155,
    "embed_id": null,
    "user": 1,
    "date_uploaded": "2013-11-15 04:30:52 UTC",
    "storage_adapter": "local"
  }
}

Update File

PUT /api/1.1/files/[id]

Update a file (and its metadata) within the Directus File Library

Name Value Description
id Integer Required The id of the file you wish to update
Data File Object This data and its architecture is based on Directus files's schema.
active Integer File's status 1=active, 2=inactive, 3=deleted
name String File name
title String File's title
location String Location of where the picture was taken, if any
type String File mime type
url String File url relativity to Directus base url
tags String Comma separated tags
caption String File caption (description)
width Integer File width
height Integer File height
size Integer File size in bytes
embed_id String ID of the embedded file. Ex Youtube ID
user Integer File owner (who uploaded the file)
date_uploaded String File uploaded date. TODO It should be an DateTime object
storage_adapter String Storage adapter used to upload the file

Example Request

$file = $client->updateFile(2, [
  'title' => 'My New File Name'
]);
client.updateFile(2, {
  title: 'My New File Name'
});

Response

Attribute Description
meta Meta Object The Directus system metadata object that provides useful information not contained within the dataset itself Meta Object: View Nested Attributes
data File Object This data and its architecture is based on the Directus file schema and can be extended with additional custom columns File Object: View Nested Attributes
{
  "meta": {
    "table": "directus_files",
    "type": "item"
  },
  "data": {
    "id": 2,
    "active": 1,
    "name": "2a05d2300cf0a8bf1a3f6567366affed.jpg",
    "url": null,
    "title": "My New File Name",
    "location": "",
    "caption": "",
    "type": "image\/jpg",
    "charset": "binary",
    "tags": "",
    "width": 594,
    "height": 447,
    "size": 52155,
    "embed_id": null,
    "user": 1,
    "date_uploaded": "2013-11-15 04:30:52 UTC",
    "storage_adapter": "local"
  }
}
Tables

Create Table

Note: Table names are case-sensitive

POST /api/1.1/tables

Creates a new table within the database. Table names must be unique within each database and are limited to letters, numbers, and - or _. After creating a new table you must assign permissions to at least one Directus user group

Name Value Description
name String Required The unique name of the table to create

Example Request

$ curl -d "name=projects" https://instance--key.directus.io/api/1.1/tables \
        -u [user-token]:
$table = $client->createTable('projects');
client.createTable('projects');

Response

Attribute Description
meta Meta Object The Directus system metadata object that provides useful information not contained within the dataset itself Meta Object: View Nested Attributes
data Table Object Collection This data and its architecture is based on Directus table schema Table Object: View Nested Attributes

Example Response

{
  "meta": {
    "type": "item",
    "table": "directus_tables"
  },
  "data": {
    "id": "projects",
    "name": "projects",
    "table_name": "projects",
    "columns": [
      {
        "id": "id",
        "name": "id",
        "column_name": "id",
        "type": "INT",
        "length": null,
        "precision": 10,
        "scale": 0,
        "sort": 1,
        "default_value": null,
        "nullable": null,
        "column_key": null,
        "extra_options": [],
        "options": [],
        "table_name": "projects",
        "required": false,
        "ui": "numeric",
        "hidden_list": false,
        "hidden_input": false,
        "relationship": null,
        "comment": ""
      },
      {
        "id": "active",
        "name": "active",
        "column_name": "active",
        "type": "INT",
        "length": null,
        "precision": 10,
        "scale": 0,
        "sort": 2,
        "default_value": "2",
        "nullable": null,
        "column_key": null,
        "extra_options": [],
        "options": [],
        "table_name": "projects",
        "required": false,
        "ui": "numeric",
        "hidden_list": false,
        "hidden_input": false,
        "relationship": null,
        "comment": ""
      }
    ],
    "primary_column": null,
    "schema": "your_database",
    "hidden": false,
    "single": false,
    "default_status": null,
    "user_create_column": null,
    "user_update_column": null,
    "date_create_column": null,
    "date_update_column": null,
    "created_at": "2016-11-26 11:15:17",
    "date_created": null,
    "comment": "",
    "row_count": 0,
    "footer": false,
    "list_view": null,
    "column_groupings": null,
    "filter_column_blacklist": null,
    "preferences": {
      "user": 1,
      "columns_visible": "",
      "table_name": "projects",
      "title": null,
      "sort": "id",
      "sort_order": "ASC",
      "status": "1,2"
    }
  }
}

Get Tables

Note: Table names are case-sensitive

GET /api/1.1/tables

Retrieve a collection of tables within Directus based on the current user's privileges

Name Value Description
include_system Boolean Default 0 Whether or not to include Directus system tables

Example Request

$ curl https://database.account.directus.io/api/1.1/tables \
        -u [user-token]:
$tables = $client->getTables(['include_system' => false]);
client.getTables({
  include_system: false
});

Response

Attribute Description
meta Meta Object The Directus system metadata object that provides useful information not contained within the dataset itself Meta Object: View Nested Attributes
data Table Object Collection This data and its architecture is based on the Directus table schema Table Object: View Nested Attributes

Example Response

{
  "meta": {
    "type": "collection",
    "table": "directus_tables"
  },
  "data": [
    {
      "name": "projects"
    },{
      "name": "articles"
    },{
      "name": "clients"
    }
  ]
}

Get Table

Note: Table names are case-sensitive

GET /api/1.1/tables/[table-name]

Get system and schema information for a specific table

Name Value Description
table-name String Required The table name you wish to get the information from
include_columns Boolean Default true Include the table columns information @TODO Not available yet
include_preferences Boolean Default true Include the table preferences @TODO Not available yet

Example Request

$ curl https://instance--key.directus.io/api/1.1/tables/projects \
        -u [user-token]:
$table = $client->getTable('projects');
client.getTable('projects');

Response

Attribute Description
meta Meta Object The Directus system metadata object that provides useful information not contained within the dataset itself Meta Object: View Nested Attributes
data Table Object This data and its architecture is based on Directus table schema Table Object: View Nested Attributes

Example Response

{
  "meta": {
    "type": "item",
    "table": "directus_tables"
  },
  "data": {
    "id":"projects",
    "table_name":"projects",
    "date_created":"2016-01-15 02:20:45",
    "comment":"",
    "hidden":false,
    "single":false,
    "is_junction_table":false,
    "user_create_column":null,
    "user_update_column":null,
    "date_create_column":null,
    "date_update_column":null,
    "footer":false,
    "columns":[
      {
         "id":"id",
         "column_name":"id",
         "type":"INT",
         "is_nullable":"NO",
         "comment":"",
         "sort":1,
         "system":true,
         "master":false,
         "hidden_list":false,
         "hidden_input":false,
         "required":true,
         "column_type":"int(11) unsigned",
         "is_writable":true,
         "ui":"numeric",
         "hidden":true,
         "options":[
             ...
         ]
      },
      {
         "id":"active",
         "column_name":"active",
         "type":"TINYINT",
         "is_nullable":"YES",
         "default_value":"2",
         "comment":"",
         "sort":2,
         "system":true,
         "master":false,
         "hidden_list":false,
         "hidden_input":false,
         "required":false,
         "column_type":"tinyint(1) unsigned",
         "is_writable":true,
         "ui":"checkbox",
         "hidden":true,
         "options":[
             ...
         ]
      }
    ],
    "preferences":{
      "user":"1",
      "columns_visible":"",
      "table_name":"projects",
      "title":null,
      "sort":"id",
      "sort_order":"ASC",
      "active":"1,2"
    }
 }
}
Columns

Create Column

Note: Table names are case-sensitive

POST /api/1.1/tables/[table-name]/columns

Create a new column within the specified table

Name Value Description
column_name String The unique name of the column to create
table_name String The table within which the column should be created
type String The datatype of the column, eg: INT
ui String The Directus Interface to use for this column
hidden_input Boolean Whether the column will be hidden (globally) on the Edit Item page
hidden_list Boolean Whether the column will be hidden (globally) on the Item Listing page
required Boolean Whether the column is required. If required, the interface's validation function will be triggered
sort Integer The sort order of the column used to override the column order in the schema
comment String A helpful note to users for this column
relationship_type String The column's relationship type (only used when storing relational data) eg: ONETOMANY, MANYTOMANY or MANYTOONE
related_table String The table name this column is related to (only used when storing relational data)
junction_table String The pivot/junction table that joins the column's table with the related table (only used when storing relational data)
junction_key_left String The column name in junction that is related to the column's table (only used when storing relational data)
junction_key_right String The column name in junction that is related to the related table (only used when storing relational data)

Example Request

$ curl -X POST -d "column_name=year&data_type=int&char_length=4&ui=numeric&comment=Year+build" \       
        https://instance--key.directus.io/api/1.1/tables/projects/columns \
        -u [user-token]:
$column = $client->createColumn([
    'name' => 'year',
    'table' => 'projects',
    'type' => 'int',
    'ui' => 'numeric',
    'comment' => 'Lorem Ipsum'
    'length' => 4
]);
client.createColumn({
  name: 'year',
  table: 'projects',
  type: 'int',
  ui: 'numeric',
  comment: 'Lorem Ipsum',
  length: 4
});

Response

Attribute Description
meta Meta Object The Directus system metadata object that provides useful information not contained within the dataset itself Meta Object: View Nested Attributes
data Column Object This data and its architecture is based on Directus columns's schema Column Object: View Nested Attributes

Example Response

{
  "meta": {
    "table": "directus_columns",
    "type": "item"
  },
  "data": {
    "id": "title",
    "column_name": "title",
    "type": "VARCHAR",
    "char_length": "100",
    "is_nullable": "YES",
    "comment": "Lorem Ipsum",
    "sort": 3,
    "system": false,
    "master": false,
    "hidden_list": false,
    "hidden_input": false,
    "required": false,
    "column_type": "varchar(100)",
    "is_writable": true,
    "ui": "textinput",
    "options": []
  }
}

Get Columns

Note: Table names are case-sensitive

GET /api/1.1/tables/[table-name]/columns

Get the system and schema information for all the columns within a specified table based on the current user's privileges

Name Value Description
table-name String Required The name of the table that contains the column to get the information

Example Request

$ curl https://instance--key.directus.io/api/1.1/tables/projects/columns \
        -u [user-token]:
$columns = $client->getColumns('projects');
client.getColumns('projects');

Response

Attribute Description
meta Meta Object The Directus system metadata object that provides useful information not contained within the dataset itself Meta Object: View Nested Attributes
data Column Object Collection This data and its architecture is based on Directus columns's schema Column Object: View Nested Attributes

Example Response

{
  "meta": {
    "table": "directus_columns",
    "type": "collection"
  },
  "data": [{
      "id": "id",
      "column_name": "id",
      "type": "INT",
      "is_nullable": "NO",
      "comment": "",
      "sort": 1,
      "system": true,
      "master": false,
      "hidden_list": false,
      "hidden_input": false,
      "required": true,
      "column_type": "int(11) unsigned",
      "is_writable": true,
      "ui": "numeric",
      "hidden": true,
      "options": []
  }, {
      "id": "title",
      "column_name": "title",
      "type": "VARCHAR",
      "char_length": "100",
      "is_nullable": "YES",
      "comment": "",
      "sort": 2,
      "system": false,
      "master": false,
      "hidden_list": false,
      "hidden_input": false,
      "required": false,
      "column_type": "varchar(100)",
      "is_writable": true,
      "ui": "textinput",
      "options": []
  }]
}

Get Column

Note: Table names are case-sensitive

GET /api/1.1/tables/[table-name]/columns/[column-name]

Get the system and schema information for a column within a specific table

Name Value Description
table-name String Required The name of the table that contains the column to get the information from
column-name String Required The name of the column you wish to get the information

Example Request

$ curl https://instance--key.directus.io/api/1.1/tables/projects/columns/title \
        -u [user-token]:
$column = $client->getColumn('projects', 'title');
client.getColumn('projects', 'title');

Response

Attribute Description
meta Meta Object The Directus system metadata object that provides useful information not contained within the dataset itself Meta Object: View Nested Attributes
data Column Object This data and its architecture is based on Directus columns's schema Column Object: View Nested Attributes

Example Response

{
  "meta": {
    "type": "item",
    "table": "directus_columns"
  },
  "data": {
    "id": "title",
    "column_name": "title",
    "type": "VARCHAR",
    "char_length": "100",
    "is_nullable": "YES",
    "comment": "",
    "sort": 2,
    "system": false,
    "master": false,
    "hidden_list": false,
    "hidden_input": false,
    "required": false,
    "column_type": "varchar(100)",
    "is_writable": true,
    "ui": "textinput",
    "options": []
  }
}

Update Column

Note: Table and column names are case-sensitive

Note: Does not update the table column-type.

PUT /api/1.1/tables/[table-name]/columns/[column-name]

Updates a column within the specified table

Name Value Description
column_name String Column name
table_name String Table name
data_type String Data type
ui String UI name
hidden_input Boolean Whether the column will be hidden in the edit form
hidden_list Boolean Whether the column will be hidden in the list page
required Boolean Whether the column is required
sort String Sort position in number
comment String Note on the column
relationship_type String Column relationship type, ONETOMANY, MANYTOMANY or MANYTOONE
related_table String The table name this column is related to
junction_table String The pivot/junction table that joins the column's table with the related table
junction_key_left String The column name in junction that is related to the column's table
junction_key_right String The column name in junction that is related to the related table

Example Request

$ curl -X PUT --data "comment=Project+Name" https://instance--key.directus.io/api/1.1/tables/projects/title \
        -u [user-token]:
client.updateColumn('projects', 'title', {
  comment: 'Project Name'
});

Response

Attribute Description
meta Meta Object The Directus system metadata object that provides useful information not contained within the dataset itself Meta Object: View Nested Attributes
data Column Object This data and its architecture is based on Directus columns's schema Column Object: View Nested Attributes

Example Response

{
  "meta": {
    "table": "directus_columns",
    "type": "item"
  },
  "data": {
    "id": "title",
    "column_name": "title",
    "type": "VARCHAR",
    "char_length": "100",
    "is_nullable": "YES",
    "comment": "Project Name",
    "sort": 3,
    "system": false,
    "master": false,
    "hidden_list": false,
    "hidden_input": false,
    "required": false,
    "column_type": "varchar(100)",
    "is_writable": true,
    "ui": "textinput",
    "options": []
  }
}

Delete Column

Note: Table names are case-sensitive

DELETE /api/1.1/tables/[table-name]/columns/[column-name]

Deletes a column from the specified table

Name Value Description
table-name String Required The name of the table that contains the column to delete
column-name String Required The name of the column you wish to delete

Example Request

$ curl -X DELETE  https://instance--key.directus.io/api/1.1/tables/projects/columns/intro \
        -u [user-token]:
$client->deleteColumn('projects', 'intro');
client.deleteColumn('projects', 'intro');

Response

Attribute Description
success Boolean Whether or not the bookmark was deleted
error Error Object Contains error information for failures Error Object: View Nested Attributes

Example Response (Success)

{
  "meta": {
    "table": "projects",
    "column": "intro"
  },
  "success": true
}

Example Response (Failure)

{
  "meta": {
    "table": "projects",
    "column": "intro"
  },
  "success": false,
  "error": {
    "message": "column `intro` does not exists in table: `projects`"
  }
}
Groups

Create Group

POST /api/1.1/groups

Create a new user group

Name Value Description
name String Required The name of the new group

Example Request

$ curl --data "name=Manager" https://instance--key.directus.io/api/1.1/groups \
  -u [user-token]:
$newGroup = $client->createGroup('Manager');
client.createGroup('Manager');

Response

Attribute Description
meta Meta Object The Directus system metadata object that provides useful information not contained within the dataset itself Meta Object: View Nested Attributes
data Group Object This data and its architecture is based on Directus groups's schema Group Object: View Nested Attributes

Example Response

{
  "meta": {
    "table": "directus_groups",
    "type": "item"
  },
  "data": {
    "id": 2,
    "name": "Manager",
    "description": null,
    "restrict_to_ip_whitelist": 0,
    "nav_override": null,
    "show_activity": 1,
    "show_messages": 1,
    "show_users": 1,
    "show_files": 1,
    "nav_blacklist": null
  }
}

Get Groups

GET /api/1.1/groups

Get system information for all user groups

Example Request

$ curl https://instance--key.directus.io/api/1.1/groups \
        -u [user-token]:
$groups = $client->getGroups();
client.getGroups();

Response

Attribute Description
meta Meta Object The Directus system metadata object that provides useful information not contained within the dataset itself Meta Object: View Nested Attributes
data Group Object Collection This data and its architecture is based on Directus groups's schema Group Object: View Nested Attributes

Example Response

{
  "meta": {
    "table": "directus_groups",
    "type": "collection",
    "total": 1,
  },
  "data": [{
    "id": 1,
    "name": "Administrator",
    "description": null,
    "restrict_to_ip_whitelist": 0,
    "nav_override": null,
    "show_activity": 1,
    "show_messages": 1,
    "show_users": 1,
    "show_files": 1,
    "nav_blacklist": null
  }]
}

Get Group

GET /api/1.1/groups/[id]

Get system information for the specified user group

Example Request

$ curl https://instance--key.directus.io/api/1.1/groups/1 \
  -u [user-token]:
$group = $client->getGroup(1);
client.getGroup(1);

Response

Attribute Description
meta Meta Object The Directus system metadata object that provides useful information not contained within the dataset itself Meta Object: View Nested Attributes
data Group Object This data and its architecture is based on Directus groups's schema Group Object: View Nested Attributes

Example Response

{
  "meta": {
    "table": "directus_groups",
    "type": "item"
  },
  "data": {
    "id": "1",
    "name": "Administrator",
    "description": null,
    "restrict_to_ip_whitelist": "0",
    "nav_override": null,
    "show_activity": "1",
    "show_messages": "1",
    "show_users": "1",
    "show_files": "1",
    "nav_blacklist": null
  }
}
Group Privileges

Create Privileges

Note: Table names are case-sensitive

POST /api/1.1/privileges/[group-id]

Create new table privileges for the specified user group

Name Value Description
group-id Integer Required The group id you wish to get the privileges from
id Integer Privilege's Unique Identification number
group_id Integer The id for the user group that should be assigned these privileges
table_name String The table name that these privileges should be applied to
allow_add Integer Permission to add/create entries in the table (See values below)
allow_edit Integer Permission to edit/update entries in the table (See values below)
allow_delete Integer Permission to delete/remove entries in the table (See values below)
allow_view Integer Permission to view/read entries in the table (See values below)
allow_alter Integer Permission to add/create entries in the table (See values below)
nav_listed Boolean If the table should be visible in the sidebar for this user group
read_field_blacklist String A CSV of column names that the group can't view (read)
write_field_blacklist String A CSV of column names that the group can't edit (update)
status_id String State of the record that this permissions belongs to (Draft, Active or Soft Deleted)

Example Request

$ curl -X POST -d "group_id=2&table_name='projects'&allow_edit=2&allow_delete=&write_field_blacklist='title,published_date'" \ https://instance--key.directus.io/api/1.1/privileges/1 \
  -u [user-token]:
$privileges = $client->createPrivileges([
  'group_id' => 2,
  'table_name' => 'projects',
  'allow_edit' => 2,
  'allow_delete' => 0,
  'write_field_blacklist' => 'title,published_date'
]);
client.createPrivileges({
  group_id: 2,
  table_name: 'projects',
  allow_edit: 2,
  allow_delete: 0,
  write_field_blacklist: 'title,published_date'
});

Response

Attribute Description
meta Meta Object The Directus system metadata object that provides useful information not contained within the dataset itself Meta Object: View Nested Attributes
data Privilege Object This data and its architecture is based on Directus Privileges's schema Privilege Object: View Nested Attributes

Example Response

{
  "meta": {
    "type": "item",
    "table": "directus_privileges"
  },
  "data": {
    "id": 2,
    "table_name": "projects",
    "group_id": 2,
    "read_field_blacklist": null,
    "write_field_blacklist": "title,published_date",
    "nav_listed": 1,
    "status_id": 0,
    "allow_view": 2,
    "allow_add": 1,
    "allow_edit": 2,
    "allow_delete": 0,
    "allow_alter": 1
  }
}

Get Privileges

GET /api/1.1/privileges/[group-id]

Get the privileges for the specified user group

Name Value Description
group-id Integer Required The group id you wish to get the privileges from

Example Request

$ curl https://instance--key.directus.io/api/1.1/privileges/1 \
  -u [user-token]:
$privileges = $client->getGroupPrivileges(1);
client.getGroupPrivileges(1);

Response

List of all the tables with their privileges for the specified user-group.

Attribute Description
meta Meta Object The Directus system metadata object that provides useful information not contained within the dataset itself Meta Object: View Nested Attributes
data Privilege Object Collection This data and its architecture is based on Directus Privileges's schema Privilege Object: View Nested Attributes

Example Request

{
  "meta": {
    "type": "item",
    "table": "directus_privileges"
  },
  "data": [{
    "id": 1,
    "table_name": "projects",
    "group_id": 1,
    "read_field_blacklist": null,
    "write_field_blacklist": null,
    "nav_listed": 1,
    "status_id": 0,
    "allow_view": 2,
    "allow_add": 1,
    "allow_edit": 2,
    "allow_delete": 2,
    "allow_alter": 1
  }]
}

Get Table Privileges

Note: Table names are case-sensitive

GET /api/1.1/privileges/[group-id]/[table-name]

Get the table privileges for a specific user group

Name Value Description
group-id Integer Required The group id you wish to get the privileges from
table-name String Required The table name you wish to get the privileges from

Example Request

$ curl https://instance--key.directus.io/api/1.1/privileges/1/projects \
  -u [user-token]:
client.getTablePrivileges(1, 'projects');

Response

Table privilege for the specified table and user-group.

Attribute Description
meta Meta Object The Directus system metadata object that provides useful information not contained within the dataset itself Meta Object: View Nested Attributes
data Privilege Object This data and its architecture is based on Directus Privileges's schema Privilege Object: View Nested Attributes

Example Response

{
  "meta": {
    "type": "item",
    "table": "directus_privileges"
  },
  "data": {
    "id": 1,
    "table_name": "projects",
    "group_id": 1,
    "read_field_blacklist": null,
    "write_field_blacklist": null,
    "nav_listed": 1,
    "status_id": 0,
    "allow_view": 2,
    "allow_add": 1,
    "allow_edit": 2,
    "allow_delete": 2,
    "allow_alter": 1
  }
}

Update Privileges

PUT /api/1.1/privileges/[group-id]/[privileges-id]

Update the specified group privileges for the specified table

Name Value Description
group-id Integer Required The group id you wish to update the privileges
privileges-id Integer Required The privilege id you wish to update
id Integer Privilege's Unique Identification number
group_id Integer Group ID
table_name String Table name that this permissions belongs to
allow_add Integer Whether the group is allow to add/create entries in the table (See values below)
allow_edit Integer Whether the group is allow to edit/update entries in the table (See values below)
allow_delete Integer Whether the group is allow to delete/remove entries in the table (See values below)
allow_view Integer Whether the group is allow to view/read entries in the table (See values below)
allow_alter Integer Whether the group is allow to add/create entries in the table (See values below)
nav_listed Boolean Whether the table should be visible in the sidebar
read_field_blacklist String List of columns that the group can't view/read
write_field_blacklist String List of columns that the group can't edit/update
status_id String State of the record that this permissions belongs to (Draft, Active or Soft Deleted)

Example Request

$ curl -X PUT --data "allow_view=1" https://instance--key.directus.io/api/1.1/privileges/1/1 \
  -u [user-token]:
$privilege = $client->updateItem('directus_privileges', 1, [
  'allow_view' => 1
]);
client.updatePrivileges(1, 1, {
  allow_view: 1
});

Response

Attribute Description
meta Meta Object The Directus system metadata object that provides useful information not contained within the dataset itself Meta Object: View Nested Attributes
data Privilege Object This data and its architecture is based on Directus Privileges's schema Privilege Object: View Nested Attributes

Example Response

{
  "meta": {
    "type": "item",
    "table": "directus_privileges"
  },
  "data": {
    "id": 2,
    "table_name": "projects",
    "group_id": 2,
    "read_field_blacklist": null,
    "write_field_blacklist": "title,published_date",
    "nav_listed": 1,
    "status_id": 0,
    "allow_view": 1,
    "allow_add": 1,
    "allow_edit": 2,
    "allow_delete": 0,
    "allow_alter": 1
  }
}
Preferences

Get Preferences

Note: Table names are case-sensitive

GET /api/1.1/tables/[table-name]/preferences

Get all preferences for a table

Name Value Description
table-name String Required The table you wish to get the preferences from

Example Request

$ curl https://instance--key.directus.io/api/1.1/tables/projects/preferences \
        -u [user-token]:
$preferences = $client->getPreferences('projects');
client.getPreferences('projects');

Response

Attribute Description
meta Meta Object The Directus system metadata object that provides useful information not contained within the dataset itself Meta Object: View Nested Attributes
data Preference Object This data and its architecture is based on Directus Preferences's schema Preference Object: View Nested Attributes

Example Response

{
  "meta": {
    "type": "item",
    "table": "directus_preferences"
  },
  "data": {
    "id": 1,
    "user": 1,
    "table_name": "projects",
    "title": null,
    "columns_visible": "title",
    "sort": "id",
    "sort_order": "ASC",
    "status": "1,2",
    "search_string": null
  }
}

Update Preference

Note: Table names are case-sensitive

PUT /api/1.1/tables/[table-name]/preferences

Update a preference within a specific table

Name Value Description
table-name String Required The table you wish to update the preferences
id Integer Preference's Unique Identification number
table_name String Name of the table
columns_visible String List of visible columns, separated by commas
sort String Result will be sorted by this column
sort_order String Sort Order (ASC=Ascending or DESC=Descending)
status String List of status values. separated by comma

Example Request

$ curl -d sort_order=DESC https://instance--key.directus.io/api/1.1/tables/projects/preferences \
        -u [user-token]:
client.updatePreferences('projects', {
  sort_order: 'DESC'
});

Response

Attribute Description
meta Meta Object The Directus system metadata object that provides useful information not contained within the dataset itself Meta Object: View Nested Attributes
data Preference Object This data and its architecture is based on Directus Preferences's schema Preference Object: View Nested Attributes

Example Response

{
  "meta": {
    "table": "directus_preferences",
    "type": "item"
  },
  "data": {
    "id": 1,
    "table_name": "projects",
    "title": null,
    "columns_visible": "title",
    "sort": "id",
    "sort_order": "DESC",
    "status": "1,2",
    "search_string": null
  }
}
Messages

Get Messages

GET /api/1.1/messages/rows

Get all of the messages for the current user

Name Value Description
max_id Integer Optional Only get messages newer than this message id

Example Request

$ curl https://instance--key.directus.io/api/1.1/messages/self \
  -u [user-token]:
$userId = 1; // default to authenticated user
$messages = $client->getMessages($userId);
// Gets messages of authenticated user
client.getMessages();

Response

Attribute Description
meta Meta Object The Directus system metadata object that provides useful information not contained within the dataset itself Meta Object: View Nested Attributes
data Message Object Collection This data and its architecture is based on Directus messages's schema Message Object: View Nested Attributes

Example Response

{
  "meta": {
    "read": 1,
    "unread": 0,
    "total": 1,
    "max_id": 20,
    "type": "collection",
    "table": "directus_messages"
  },
  "data": [
    {
      "id": 1,
      "from": 1,
      "subject": "Sunday Morning meeting",
      "message": "Cancelled!",
      "attachment": null,
      "datetime": "2016-11-02T13:04:47-04:00",
      "response_to": null,
      "read": 1,
      "responses": {
        "rows": []
      },
      "recipients": "2,1",
      "date_updated": "2016-11-02T13:04:47-04:00"
    }
  ]
}

Get Message

GET /api/1.1/messages/rows/[message-id]

Get a specific message by its ID (if it belongs to the given or authenticated user)

Name Value Description
message-id Integer Required The id of the message you wish to get

Example Request

$ curl https://instance--key.directus.io/api/1.1/messages/1 \
  -u [user-token]:
$messageId = 1;
$userId = 2; // On db connection only
$messages = $client->getMessage($messageId, $userId);
const messageId = 1;
client.getMessage(messageId);

Response

Attribute Description
meta Meta Object The Directus system metadata object that provides useful information not contained within the dataset itself Meta Object: View Nested Attributes
data Message Object This data and its architecture is based on Directus messages's schema Message Object: View Nested Attributes

Example Response

{
  "meta": {
    "read": 1,
    "unread": 0,
    "total": 1,
    "max_id": 20,
    "type": "collection",
    "table": "directus_messages"
  },
  "data": {
    "id": 1,
    "from": 1,
    "subject": "Sunday Morning meeting",
    "message": "Cancelled!",
    "attachment": null,
    "datetime": "2016-11-02T13:04:47-04:00",
    "response_to": null,
    "read": 1,
    "responses": {
      "rows": []
    },
    "recipients": "2,1",
    "date_updated": "2016-11-02T13:04:47-04:00"
  }
}
Activity

Get Activities

GET /api/1.1/activity

Get all the activity records within Directus

Name Value Description
limit Integer Default 200 The number of items to request
offset Integer Default 0 The offset for for the items
in[field] String Optional Only list records that its field matches one of given value. Can be separated by commas in[id]=1,2
ids String Optional Only list records that its field matches one of given value. Can be separated by commas ids=1,2. Same as in[id]=1,2
filters Optional Use Filter Object to filter the result.

Example Request

$ curl -g https://instance--key.directus.io/api/1.1/activity&filters[table_name]=projects \
  -u [user-token]:
$activity = $client->getActivity([
  'filters' => [
    'table_name' => projects
  ]
]);
client.getActivity({
  filters: {
    table_name: 'projects'
  }
})

Response

Attribute Description
meta Meta Object The Directus system metadata object that provides useful information not contained within the dataset itself Meta Object: View Nested Attributes
data Activity Object Collection This data and its architecture is based on Directus activity's schema Activity Object: View Nested Attributes

Example Response

{
  "meta": {
    "table": "directus_activity",
    "type": "collection",
    "total": 2,
  },
  "data": [{
      "id": 1,
      "identifier": "School Website",
      "action": "ADD",
      "table_name": "projects",
      "row_id": 5,
      "user": 1,
      "datetime": "2016-12-06T09:46:40-05:00",
      "type": "ENTRY",
      "data": "<json-data-used>"
    },{
      "id": 2,
      "identifier": "Benjamin School for gifted children Website",
      "action": "UPDATE",
      "table_name": "projects",
      "row_id": 5,
      "user": 1,
      "datetime": "2016-12-07T08:58:00-05:00",
      "type": "ENTRY",
      "data": "<json-data-used>"
    }]
}
Bookmarks

Get Bookmarks

GET /api/1.1/bookmarks

Get all the bookmarks

Example Request

$ curl https://instance--key.directus.io/api/1.1/bookmarks \
  -u [user-token]:
$bookmarks = $client->getBookmarks();
client.getBookmarks();

Response

Attribute Description
meta Meta Object The Directus system metadata object that provides useful information not contained within the dataset itself Meta Object: View Nested Attributes
data Bookmark Object Collection This data and its architecture is based on Directus bookmarks's schema Bookmark Object: View Nested Attributes

Example Response

{
  "meta": {
    "table": "directus_bookmarks",
    "type": "collection",
    "total": 2,
  },
  "data": [{
      "id": 1,
      "user": 1,
      "title": "Draft Articles",
      "url": "tables/articles/pref/Draft Articles",
      "icon_class": null,
      "active": null,
      "section": "search"
    },
    {
      "id": 2,
      "user": 1,
      "title": "Published News",
      "url": "tables/news/pref/Published News",
      "icon_class": null,
      "active": null,
      "section": "search"
    }]
}

Get User Bookmarks

GET /api/1.1/bookmarks/self

Get all of the bookmarks for the current user

Example Request

$ curl https://instance--key.directus.io/api/1.1/bookmarks/self \
  -u [user-token]:
// Using the SDK with API connection
// you can fetch bookmarks same as get bookmarks method
$bookmarks = $client->getBookmarks();

// Using the SDK with DB connection you can fetch any bookmarks
// So you `1` here is the user id.
$bookmarks = $client->getBookmarks(1);
client.getUserBookmarks();

Response

Attribute Description
meta Meta Object The Directus system metadata object that provides useful information not contained within the dataset itself Meta Object: View Nested Attributes
data Bookmark Object Collection This data and its architecture is based on Directus bookmarks's schema Bookmark Object: View Nested Attributes

Example Response

{
  "meta": {
    "table": "directus_bookmarks",
    "type": "collection",
    "total": 2,
  },
  "data": [{
      "id": 1,
      "user": 1,
      "title": "Draft Articles",
      "url": "tables/articles/pref/Draft Articles",
      "icon_class": null,
      "active": null,
      "section": "search"
    },
    {
      "id": 2,
      "user": 1,
      "title": "Published News",
      "url": "tables/news/pref/Published News",
      "icon_class": null,
      "active": null,
      "section": "search"
    }]
}

Get Bookmark

GET /api/1.1/bookmarks/[bookmark-id]

Get all of the bookmarks for the current user

Example Request

$ curl https://instance--key.directus.io/api/1.1/bookmarks/1 \
  -u [user-token]:
$bookmark = $client->getBookmark(1);
client.getBookmark(1);

Response

Attribute Description
meta Meta Object The Directus system metadata object that provides useful information not contained within the dataset itself Meta Object: View Nested Attributes
data Bookmark Object This data and its architecture is based on Directus bookmarks's schema

Example Response

{
  "meta": {
    "table": "directus_bookmarks",
    "type": "item",
  },
  "data": {
    "id": 1,
    "user": 1,
    "title": "Draft Articles",
    "url": "tables/articles/pref/Draft Articles",
    "icon_class": null,
    "active": null,
    "section": "search"
  }
}

Create Bookmark

POST /api/1.1/bookmarks

Create a new bookmark

Name Value Description
user Integer [Directus user id] This assigns the bookmark to a specific user (there's a ticket to allow for "global" bookmarks using NULL) (Only using local connection)
title String The text to display in the navigation menu
url String The path to navigate to when clicked, relative to the Directus root
icon_class String Deprecated
active String Deprecated
section String ["search" or "other"] Which nav section to show the link within. User generated bookmarks use "search", while all system links go within "other"

Note: Creating a bookmark will create only a link which will point to an url given.

Note: Creating a bookmark saving a result filtered with different parameters you have to create a preferences with the same title as the bookmark, having the url formatted as follow /tables/[table-name]/pref/[bookmark-title]

Example Request

$ curl --data "title=Draft+Articles&table_name=articles&status=2" \
        https://instance--key.directus.io/api/1.1/bookmarks \
                -u [user-token]:
$bookmark = $client->createBookmark([
  'title' => 'Draft Articles',
  'table_name' => 'articles',
  'status' => '2'
]);
client.createBookmark({
  title: 'Draft Articles',
  table_name: 'articles',
  status: 2
});

Response

Attribute Description
meta Meta Object The Directus system metadata object that provides useful information not contained within the dataset itself Meta Object: View Nested Attributes
data Bookmark Object This data and its architecture is based on Directus bookmarks's schema Bookmark Object: View Nested Attributes

Example Response

{
  "meta": {
    "table": "directus_bookmarks",
    "type": "item",
  },
  "data": {
    "id": 1,
    "user": 1,
    "title": "Draft Articles",
    "url": "tables/articles/pref/Draft Articles",
    "icon_class": null,
    "active": null,
    "section": "search"
  }
}

Delete Bookmark

DELETE /api/1.1/bookmarks/[bookmark-id]

Deletes a bookmark

Example Request

$ curl -X DELETE https://instance--key.directus.io/api/1.1/bookmarks/1 \
  -u [user-token]:
$bookmark = $client->deleteBookmark(1);
client.deleteBookmark(1);

Response

Attribute Description
success Boolean Whether or not the bookmark was deleted
error Error Object This object contains error information (if any) Error Object: View Nested Attributes

Example Request (Success)

{
  "success": true
}

Example Request (Failure)

{
  "success": false,
  "error": {
    "message": "bookmark_not_found"
  }
}
Settings

Get Settings

GET /api/1.1/settings

Get all Directus settings

Example Request

$ curl https://instance--key.directus.io/api/1.1/settings \
  -u [user-token]:
$settings = $client->getSettings();
client.getSettings();

Response

Attribute Description
meta Meta Object The Directus system metadata object that provides useful information not contained within the dataset itself Meta Object: View Nested Attributes
data object This data and its architecture is based on Directus settings's content

Example Response

{
  "meta": {
    "type": "item",
    "table": "directus_settings"
  },
  "data": {
    "global": {
      "cms_user_auto_sign_out": "60",
      "project_name": "Directus Demo",
      "project_url": "http:\/\/examplesite.dev\/",
      "cms_color": "#7ac943",
      "rows_per_page": "200",
      "cms_thumbnail_url": ""
    },
    "files": {
      "allowed_thumbnails": "",
      "thumbnail_quality": "100",
      "thumbnail_size": "200",
      "file_naming": "file_id",
      "thumbnail_crop_enabled": "1",
      "youtube_api_key": ""
    }
  }
}

Get Settings By Type

GET /api/1.1/settings/[collection-name]

Get all Directus settings for the specified collection

Name Value Description
collection-name String Required The collection name you wish to get the settings

Example Request

$ curl https://instance--key.directus.io/api/1.1/settings/global \
  -u [user-token]:
$settings = $client->getSettingsByCollection('global');
client.getSettingsByCollection('global');

Response

Attribute Description
meta Meta Object The Directus system metadata object that provides useful information not contained within the dataset itself Meta Object: View Nested Attributes
data object This data and its architecture is based on Directus settings's content

Example Request

{
  "meta": {
    "type": "item",
    "table": "directus_settings",
    "setting_collection": "global"
  },
  "data": {
    "cms_user_auto_sign_out": "60",
    "project_name": "Directus Demo",
    "project_url": "http:\/\/examplesite.dev\/",
    "cms_color": "#7ac943",
    "rows_per_page": "200",
    "cms_thumbnail_url": ""
  }
}

Update Settings

Note: If the setting doesn't not exist it will create a new one

PUT /api/1.1/settings/[collection-name]

Update the Directus settings for the specified collection

Name Value Description
collection-name Integer Required The setting collection name you wish to edit
data Array Required Pair of key-value setting to be updated, eg: rows_per_page=50

Example Request

$ curl --data "rows_per_page=100" https://instance--key.directus.io/api/1.1/settings/global \
  -u [user-token]:
$setting = $client->updateSettings('global', [
  'rows_per_page' => 100
])
client.updateSettings('global', {
  rows_per_page: 100
});

Response

Attribute Description
meta Meta Object The Directus system metadata object that provides useful information not contained within the dataset itself Meta Object: View Nested Attributes
data object This data and its architecture is based on Directus settings's content

Example Response

{
  "meta": {
    "type": "item",
    "table": "directus_settings",
    "setting_collection": "global"
  },
  "data": {
    "cms_user_auto_sign_out": "60",
    "project_name": "Directus Demo",
    "project_url": "http:\/\/examplesite.dev\/",
    "cms_color": "#7ac943",
    "rows_per_page": "100",
    "cms_thumbnail_url": ""
  }
}
Utils

Get Random Alphanumeric String

Note: This does not use any sophisticated random algorithm.

POST /api/1.1/random

Get a random string

Name Value Description
length String Default 32 The length of the random string

Example Request

$ curl --data "length=64" \
        https://instance--key.directus.io/api/1.1/random \
        -u [user-token]:
$random = $client->getRandom(['length' => 64]);
var random = client.getRandom({length: 64});

Response

Attribute Description
data Containing a random key with the new generated random value.

Example Response

{
  "success": true,
  "data": {
    "random": "123456789abc"
  }
}

Get a hashed value

POST /api/1.1/hash

Get a hash value from a given string

Name Value Description
string String Required The string to be hashed
hasher String Default core The hasher used to hash the given string
options Object Default empty The hasher options

Supported hashers

Name Description
core The php default hasher algorithm used in PASSWORD_DEFAULT
bcrypt BCrypt algorithm using password_hash
sha1 Generated a 160-bit hash value
sha224 Generated a 224-bit hash value
sha256 Generated a 256-bit hash value
sha384 Generated a 384-bit hash value
sha512 Generated a 512-bit hash value

Example Request

$ curl --data "string=secret&hasher=bcrypt" \
        https://instance--key.directus.io/api/1.1/hash \
        -u [user-token]:
$hash = $client->hash('secret', [
  'hasher' => 'bcrypt'
]);
var hash = client.hash('secret', {
  hasher: 'bcrypt'
});

Response

Attribute Description
data Containing a hash key with the hashed value.

Example Response

{
  "success": true,
  "data": {
    "hash": "$2y$valueHashed"
  }
}
PHP SDK

Creating Data

Method Parameters Description
createItem table, data Creates a new item within the given table
createActivity data Creates an activity log
createBookmark data Creates a bookmark
createColumn data Creates a new column
createFile data Creates a new file
createGroup data Creates a new group
createMessage data Creates/Sends a new message
sendMessage data createMessage alias
createPreferences data Creates a table preferences
createPrivileges data Creates a table privileges (Permissions)
createSettings data Creates a new setting
createTable name, params Creates a new table
createUIOptions data Creates a new UI options
createUser data Creates a new user

Create Item

Parameter Type Description
table String The Table name where the data are going to be inserted
data Array Data to be inserted in table. All this data attributes will depend on your table columns

Returns

An Item object containing the new created item.

Example Request

$article = $client->createItem('articles', [
  'title' => 'New Article',
  'body' => 'Some text'
]);

// echo $article->title;

Create Bookmark

Column Type Description
table_name String Bookmark Table name
title String Bookmark title
columns_visible String List of column separated by comma
search_string String List of filters separated by comma. Format column:operator:value
sort String Sort column
sort_order String Sort column order. (ASC or DESC)
status String List of status separated by comma

Returns

An Entry object containing the new bookmark created.

Example Request

$bookmark = $client->createBookmark([
  'title' => 'Draft Articles',
  'table_name' => 'articles',
  'status' => '2'
]);

// echo $bookmark->title;

Create Column

Column Type Description
name String Column name
table String Table name
type String Data type
ui String UI name
hidden_input Boolean Whether the column will be hidden in the edit form
hidden_list Boolean Whether the column will be hidden in the list page
required Boolean Whether the column is required
sort String Sort position in number
comment String Note on the column
relationship_type String Column relationship type, ONETOMANY, MANYTOMANY or MANYTOONE
related_table String The table name this column is related to
junction_table String The pivot/junction table that joins the column's table with the related table
junction_key_left String The column name in junction that is related to the column's table
junction_key_right String The column name in junction that is related to the related table

@TODO Make most of the attributes "guessed/automated", for example single_ui should should has related_table to directus_files and junction_key_right to the same column name.

Example Request

$column = $client->createColumn([
    'name' => 'title',
    'table' => 'articles',
    'type' => 'varchar',
    'ui' => 'textinput',
    'length' => 255
]);
$column = $client->createColumn([
    'name' => 'image',
    'table' => 'articles',
    'type' => 'int',
    'ui' => 'single_file',
    'related_table' => 'directus_files',
    'junction_key_right' => 'image' // same as the title
]);
$column = $client->createColumn([
    'name' => 'posts',
    'table' => 'authors',
    'type' => 'ALIAS',
    'ui' => 'one_to_many',
    'relationship_type' => 'ONETOMANY',
    'related_table' => 'articles',
    'junction_key_right' => 'author'
]);

Create Group

Column Type Description
name String Group name
restrict_to_ip_whitelist String List of IPs allowed to authenticate, separated by comma

Example Request

$group = $client->createGroup([
    'name' => 'Editors'
]);

Create/Send Messages

Column Type Description
from Integer Sender user id
to Array List of users id, separated by comma
toGroup Array List of groups id, separated by comma
subject String Message subject
message String Message content
attachments Array @TODO List of files to add to the message

@TODO Send/Create responses without the need to specify each recipients.

Returns

Entry object containing the new created message.

Example Requests

Sending message to two users.

$message = $client->createMessage([
    'from' => 1,
    'to' => [2, 5],
    'subject' => 'New Design review',
    'message' => 'I want some feedback on this new design.'
]);

Sending message to two groups.

// same as createMessage
$message = $client->sendMessage([
    'from' => 1,
    'toGroup' => [1, 3], // 1 = Administrator, 3 = Editors
    'subject' => 'Tomorrow Meeting',
    'message' => 'I want to you all know that tomorrow meeting was cancelled.'
]);

Message Item Attributes

Attribute Type Description
id Integer Message ID
from Integer Sender ID
recipients String List of Recipients separated by comma. @TODO: it should be an array
subject String Message subject
responses Array List of responses messages
response_to Integer Parent message (replied to this message id)
read Integer Whether the message was read by the authenticated user. @TODO It should be bool

Create Preferences

Column Type Description
user Integer User ID that this preferences belongs to
table_name String Table name that this preferences belongs to
columns_visible String List of visible column separated by comma
sort String Sort column
sort_order String Sort column order. ASC or DESC
status String List of status separated by comma

Returns

An Entry object containing the new preference created.

Example Request

$preference = $client->createPreferences([
  'user' => 1,
  'table_name' => 'articles',
  'columns_visible' => 'title,content,author,published_date'
  'status' => '2'
]);

// echo $preference->columns_visible;

Create Privileges

Column Type Description
group_id Integer Group ID
table_name String Table name that these privileges belong to
allow_add Integer Allow to add/create items in the table:
0 (None), 1 (Add)
allow_edit Integer Allow to edit/update items in the table:
0 (None), 1 (Edit Mine), 2 (Edit All)
allow_delete Integer Allow to delete/remove items in the table:
0 (None), 1 (Delete Mine), 2 (Delete All)
allow_view Integer Allow to view/read items in the table:
0 (None), 1 (View Mine), 2 (View All)
allow_alter Integer Allow to add/create items in the table:
0 (None), 1 (Alter)
nav_listed Boolean Whether the table should be visible in the sidebar or not
read_field_blacklist String CSV of columns that the group can't view/read
write_field_blacklist String CSV of columns that the group can't edit/update
status_id String State of the record that these privileges belongs to. eg: Interns can edit Drafts, but only view Published items

Returns

An Entry object containing the new privileges created.

Example Request

$privileges = $client->createPrivileges([
  'group_id' => 2,
  'table_name' => 'articles',
  'allow_edit' => 2,
  'allow_delete' => 0,
  'write_field_blacklist' => 'title,published_date'
]);

// echo $privileges->allow_edit;

Create Table

Parameter Type Description
name String New table name
data Array Not defined yet

Returns

An Entry (Item) object containing the new table created privileges.

Example Request

$privileges = $client->createTable('comments');

// echo $privileges->allow_edit;

Create Column Options

Column Type Description
column String Column name
table String Column table name
ui String Column UI name
options Array UI Options

Returns

Entry object containing all the column options.

Example Request

$options = $client->createColumnUIOptions([
    'column' => 'slug',
    'table' => 'articles',
    'ui' => 'textinput',
    'options' => [
        'readonly' => 1,
        'placeholder' => 'Title slug'
    ]
]);

// echo $options->placeholder;

Create User

Column Type Description
active Integer User's status. By default 1=active, 2-inactive, 3=deleted
email Required String User's unique email address
first_name String User first name
last_name String User last name
password String Plain text password
token String User's unique API access token
group Integer User's group ID
email_messages Boolean Whether the user wants to receive email notification
avatar String Avatar url
avatar_file_id Integer Use a file id as avatar
language String User's default language. Language Supported en (English), es (Spanish), de (German), fr (French), it (Italian), zh-hans (Simplified Chinese) and nl (Dutch)
timezone String User's default timezone
position String User's position on the project/company
location String User's location in the world or universe
phone String User's phone number
address String User's address
city String User's city
state String User's state
zip String User's zip code

Returns

An Entry object containing the new created user.

Example Request

$user = $client->createUser([
  'email' => 'user@website.local',
  'first_name' => 'John',
  'last_name' => 'Bohannon',
  'password' => 'plain-text-password',
  'token' => 'secret-token'
]);

// echo $user->email;
// @TODO: echo $user->getEmail(); (UserEntry Object)

User Item Attributes

Column Type Description
id Integer User ID
active Integer User's status. 1=active, 2=inactive, 3=deleted
email String User's unique email address
first_name String User first name
last_name String User last name
password String hashed password IS THIS NEEDED?
token String User's unique API access token
group Integer User's group ID
email_messages Boolean Whether the user wants to receive email notification
avatar String Avatar url
avatar_file_id Integer File id used as avatar
language String User's default language. Languages Supported en (English), es (Spanish), de (German), fr (French), it (Italian), zh-hans (Simplified Chinese) and nl (Dutch)
timezone String User's default timezone
position String User's position on the project/company
location String User's location in the world or universe
phone String User's phone number
address String User's address
city String User's city
state String User's state
zip String User's zip code

Create File

Parameter Type Description
file File New file
File Parameter Type Description
path Required String Local path of the file.
url (@TODO) String URL of the file to upload, OR a YouTube/Vimeo link to be embedded
title String File's title
tags String Comma separated tags
caption String File caption (Description)

Returns

An Entry object containing the new created file.

@TODO Returns a FileEntry Object.

Example Request

// From a local file
$file = $client->createFile(new File('/path/to/the/file.jpg', [
  'title' => 'Company Group picture',
  'tags' => 'company, employees, team',
  'caption' => 'Whole company at Christmas party'
]);

// echo '<h1>' . $file->title . '</h1>;
// echo '<p>' . $file->caption . '</p>';
// echo '<img src="' . $client->getBaseUrl() . $file->url . '">';
// @TODO: $file->getTitle();

@TODO

File Object Attributes

Column Type Description
id Integer File ID
active Integer File's status. 1=active, 2=inactive, 3=deleted
name String File name
title String File's title
location String Location of where the picture was taken (if any)
type String File mime type
url String File url relativity to Directus base url
tags String Comma separated tags
caption String File caption (Description)
width Integer File width
height Integer File height
size Integer File size in bytes
embed_id String ID of the embedded file. Ex Youtube ID
user Integer File owner (who uploaded the file)
date_uploaded String File uploaded date @TODO It should be an DateTime object
storage_adapter String Storage adapter used to upload the file

Getting Data

Method Parameter Description
getActivity params Get Directus Activity
getItems table, params Collection of rows (items) for a given table
getItem table, id, params Details for a specific table row (item)
getUsers params Collection of users
getUser id, params Details for a specific user
getFiles params Collection of files
getFile id, params Details for a specific file
getGroups params Collection of all Directus user-groups
getGroup id, params Details for a specific user-group
getGroupPrivileges group_id Privileges for a given user-group
getSettings None All Directus Setting
getSettingsByCollection collection All Directus Settings in a given collection
getMessages user Collection of messages
getMessage id Details for a specific message
getTables params Collection of tables viewable by authenticated user
getTable table Collection of latest Directus activity
getColumns table, params Collection of the column details for a given table
getColumn table, column Details for a specific column in a given table

@TODO: More helpers

Returns

An Entry or EntryCollection object containing the fetched data.

Get Activity

Parameter Type Description
params Array Customizable options

Example Request

$activities = $client->getActivity([
  'filters' => [
    'table_name' => 'articles'
  ]
]);

foreach($activities as $activity) {
  echo $activity->action;
}

Get Items

Parameter Type Description
table String The Table name to fetch data from
params Array Customizable options

Example Request

$articles = $client->getItems('articles');

foreach($articles as $article) {
  echo $article->title;
}

Get Item by ID

Parameter Type Description
table String The Table name to fetch data from
id Mixed The record id

Example Request

$article = $client->getItem('articles', 1);
echo $article->title;

Get Users

Parameter Type Description
params Array Customizable options

Example Request

$users = $client->getUsers([
  'order' => ['email' => 'ASC']
]);

foreach($users as $user) {
  echo $user->email;
}

Get User by ID

Parameter Type Description
id Integer The user id

Example Request

$user = $client->getUser(1);
echo $user->email;

@TODO

Returns

An UserEntry object containing the user information.

Get Files

Parameter Type Description
params Array Customizable options

Example Request

$files = $client->getFiles([
  'order' => ['size' => 'DESC']
]);

foreach($files as $file) {
  echo $file->email;
}

Get File by ID

Parameter Type Description
id Integer The file

Example Request

$file = $client->getFile(1);
echo $file->name;

@TODO

Returns

A FileEntry object containing the file information.

Get Groups

Parameter Type Description
params Array Customizable options

Example Request

$groups = $client->getGroups([
  'order' => ['name' => 'ASC']
]);

foreach($groups as $group) {
  echo $group->name;
}

Get Group by ID

Parameter Type Description
id Integer The group id

Example Request

$group = $client->getGroup(1);
echo $group->name;

@TODO

Returns

A GroupEntry object containing the group information.

Get Group Privileges

Parameter Type Description
id Integer The group id

Example Request

$privileges = $client->getGroupsPrivileges(1);

foreach($privileges as $privilege) {
  echo $privilege->table_name;
  echo $privilege->allow_view;
}

Get Settings

Parameter Type Description
None

Example Request

$settings = $client->getSettings();
echo $settings->global->project_name

@TODO

Returns

A SettingEntry object containing the setting information.

Get Settings by Collection

Parameter Type Description
collection String Name of the collection

Example Request

$settings = $client->getSettingsByCollection('global');
echo $settings->project_name

Get Messages

Parameter Type Description
userId Integer User ID messages list
// Using the API Client it's going to be default to the authenticated user.
$messages = $client->getMessages(1);

Get Message

Parameter Type Description
id Integer The message id
user Integer The user id (only for db connection)
$message = $client->getMessage(1);

Get Tables

Parameter Type Description
params Array Customizable options

Example Request

$tables = $client->getTables([
  'include_system' => 1
]);

foreach($tables as $table) {
  echo $table->name;
}

Params

Parameter Type Description
include_system Boolean Include the core tables

Get Table

Parameter Type Description
table String The Table name
params Array Customizable options

Example Request

$table = $client->getTable('directus_groups');
echo $table->name;

Get Table Columns

Parameter Type Description
table String The Table name
params Array Customizable options

Example Request

$columns = $client->getTableColumns('articles');

foreach($columns as $column) {
  echo $column->name;
}

Get Table Column

Parameter Type Description
table String The Table name
column String The column name

Example Request

$column = $client->getTableColumn('articles', 'title');
$isRequired = $column->required;

Returns

A Entry object containing the setting information.

Get Parameters

Some methods accepts parameters to alter/filter the collection result.

order

Sort the result by one or more columns.

Example Request

$params = [
  'order' => [
    'id' => 'ASC',
    'title' => 'DESC'
  ]
];

$articles = $client->getItems('articles', $params);

orderBy

Sort by only one column.

Example Request

$params = [
  'orderBy' => 'title'
];

$articles = $client->getItems('articles', $params);

orderDirection

Sort orderBy in this direction. ASC or DESC. Default to ASC.

Example Request

$params = [
  'orderBy' => 'title',
  'orderDirection' => 'DESC'
];

$articles = $client->getItems('articles', $params);

limit

Limit the numbers of records to be returned.

Example Request

$params = [
  'limit' => 100
];

$articles = $client->getItems('articles', $params);

offset

Skip this many rows.

Example Request

$params = [
  'limit' => 100,
  'offset' => 50
];

$articles = $client->getItems('articles', $params);

status

Return only records that has this status. To include multiple status, it has to be separated by comma.

Example Request

$params = [
  'status' => [1, 2]
];

$articles = $client->getItems('articles', $params);

ids

A comma-separated list of IDs.

Example Request

$params = [
   'ids' => [2, 4, 11]
];

$articles = $client->getItems('articles', $params);

filters

Filter the request by using any of the supported operators.

Example Request

$params = [
  'filters' => [
    'column_name' => ['operator' => 'value']
  ]
];

$articles = $client->getItems('articles, [
  'filters' => ['title' => ['like' => 'movies']]
]);

// Not using a `operator` is default to equal to.
$articles = $client->getItems('articles, [
  'filters' => ['slug' => 'lorem-ipsum']
]);

Supported Operators

Operator Description
=, eq, None Equal to
<>, !=, neq Not Equal to
<, lt Less than
<=, lte Less than or equal to
>, gt Greater than
>=, gte Greater than or equal to
in Match one of the value in the list
nin Not match any value in the list
null Is Null
nnull (@TODO) Is Not Null
contains (@TODO) Contains a string
ncontains (@TODO) Not Contains a string
between (@TODO) Is Between
empty (@TODO) Is Empty
nempty (@TODO) Is Not Empty
has (@TODO) Has one or more related items

Updating data

Method Parameter Description
updateItem table, id, data Updates the record with the given id in table with data
updateUser id, data Updates the given user id with the given data
updateFile id, data Updates the give file id with the given data

@TODO More helpers

Returns

An Entry object containing the updated data.

Update Item

Parameter Type Description
table String The Table name
id Mixed The id of the record to update
data Array Data to update

Update User

Parameter Type Description
id Integer The id of the user to update
data Array Data to update

User Data

Column Type Description
active Integer User's status. By default 1=active, 2-inactive, 3=deleted
email Required String User's unique email address
first_name String User first name
last_name String User last name
password String Plain text password, will be hashed on the server side
token String User's unique API access token
group Integer User's group ID
email_messages Integer Whether the user wants to receive email notification.
avatar String Avatar url
avatar_file_id Integer Use a file id as avatar
language String User's default language. Language Supported en (English), es (Spanish), de (German), fr (French), it (Italian), zh-hans (Simplified Chinese) and nl (Dutch)
timezone String User's default timezone
position String User's position on the project/company
location String User's location in the world or universe
phone String User's phone number
address String User's address
city String User's city
state String User's state
zip String User's zip code

Update File

Parameter Type Description
id Integer The id of the file to update
data Array File Data to update

Example Requests

$updatedFile = $client->updateFile(1, ['title' => 'New Design']);

// echo $updatedFile->title;
$updatedFile = $client->updateFile(1, new File('/path/to/file'));

// echo $updatedFile->url;

Deleting Data

Method Parameter Description
deleteItem table, id Deletes the record with the given id in table
deleteBookmark id Deletes the given bookmark id
deleteColumn name. table Deletes the tiven column name in the given table name
deleteFile id Deletes the give file id
deleteGroup id Creates a new group
deleteTable name Creates a new table
deleteUser id Deletes the given user id

Returns

Nothing is returned.

@TODO Return whether or not were deleted.

Delete Item

Parameter Type Description
table String The table name
id Integer The id of the record to delete in table

Example Request

$client->deleteItem('articles', 1);

Delete Bookmark

Parameter Type Description
id Integer The id of the bookmark to delete

Example Request

$client->deleteBookmark(1);

Delete Column

Parameter Type Description
name String The column name to delete
table String The table the colum belongs to

Example Request

$client->deleteColumn('slug', 'articles');

Delete File

Parameter Type Description
id Integer The id of the file to delete

Example Request

$client->deleteFile(1);

Delete Group

Parameter Type Description
id Integer The id of the group to delete

Example Request

$client->deleteGroup(1);

Delete Table

Parameter Type Description
name String The name of the table to delete

Example Request

$client->deleteTable('comments');

Delete User

Parameter Type Description
id Integer The id of the user to delete

Example Request

$client->deleteUser(1);
JS SDK

Installation & Usage

Install the package via npm npm install directus-sdk-javascript

Initialize the SDK object with your the desired api key and url

const SDK = require('directus-sdk-javascript');

const client = new SDK(
  'api-key-12345',
  'http://directus.url/api/', // Directus-hosted or own server
  1.1 // API Version
);

All methods can be used with either callbacks or promises.

client.getEntries('projects', (err, res) => {
  if(err) throw err;
  console.log(res);
});
client.getEntries('projects')
  .then(res => {
    console.log(res);
  })
  .catch(err => {
    throw err;
  });