SDK JS

A lightweight JavaScript library that makes working with the Directus API even easier. It keeps you logged in, handles token management, and provides quick access to all API Endpoints.

Installation

You can install the SDK from npm by running:

npm install @directus/sdk-js
import DirectusSDK from "@directus/sdk-js";

const client = new DirectusSDK();

Alternatively, you can use the bundle hosted on a static npm cdn:

<script src="https://unpkg.com/@directus/sdk-js@5.3.4/dist/directus-sdk.umd.min.js"></script>

<script>
  const client = new DirectusSDK();
</script>

Usage

Authentication

You can connect and login to the API in two ways:

Using JWT

If you're making API requests from client side JS, you should login using the login method. The SDK will fetch an access token based on the credentials and use that for all subsequent requests.



 

 
 
 
 
 
 

import DirectusSDK from "@directus/sdk-js";

const client = new DirectusSDK();

client.login({
  url: "https://demo-api.directus.app/",
  project: "_",
  email: "admin@example.com",
  password: "password"
});

Staying logged in

The SDK will automatically refresh the token until you call the .logout() method.

You can provide a storage method to persist the token across refreshes and browser re-opens:






 


import DirectusSDK from "@directus/sdk-js";

const client = new DirectusSDK({
  url: "https://demo-api.directus.app/",
  project: "_",
  storage: window.localStorage
});

This storage can be any provider, as long as it has synchronous .getItem() and .setItem() methods. window.localStorage and window.sessionStorage work natively in the browser.

Using a static access token Alternatively, you can connect to the API with a static token (as controlled by the token field in the directus_users collection). This token doesn't expire and thus shouldn't be used on the client side.



 
 
 
 
 

import DirectusSDK from "@directus/sdk-js";

const client = new DirectusSDK({
  url: "https://demo-api.directus.app/",
  project: "_",
  token: "demo"
});

TIP

If you're using solely routes and data with public access, you don't have to log in.

Requests

All methods return a promise that either resolves with the requested data, or rejects with the reason why.

client.getItems("movies")
  .then(data => {
    // Do something with the data
  })
  .catch(error => console.error(error));

This also means that you can use the SDK with async/await:

async function fetchAllItems() {
  const data = await client.getItems("movies");
  return data;
}

Reference

If you think a method is missing, please reach out on GitHub or Slack!

Authentication

login(credentials)

Login to the API

The credentials object has the following structure:

{
  email: "admin@example.com",
  password: "password",

  // Optional:
  url: "https://demo-api.directus.app/",
  project: "_", // Defaults to '_'
  persist: true // Defaults to true
}

WARNING

Make sure to provide the url of the API you're trying to log in to before running the login() method if you don't provide the url in the credentials object.

Login to the demo API without keeping the user logged in

client.login({
  email: "admin@example.com",
  password: "password",
  persist: false
});

Login to a previously defined API URL

client.url = "https://demo-api.directus.app/"

client.login({
  email: "admin@example.com",
  password: "password"
});

logout()

Make the SDK forget the token, project, and URL of the API.

client.logout();

refresh(token)

Will fetch a new access token based on the provided token.

Refresh a token stored in sessionStorage with a new token.

const savedToken = window.sessionStorage.getItem("token");

client.refresh(savedToken)
  .then(({ token }) => {
    window.sessionStorage.setItem("token", token);
  });

TIP

If you use the login() method, you most likely don't need to touch this one as it's being managed for you.


refreshIfNeeded()

Checks if the currently used token is about to expire (< 30s until expiry) and will fetch a new one if that's the case.

client.refreshIfNeeded();

TIP

If you use the login() method, you most likely don't need to touch this one as it's being managed for you.


requestPasswordReset(email)

Request a reset-password email based on the given email

client.requestPasswordReset("admin@example.com");

Activity

getActivity(params = {})

Get the items from directus_activity.

Get the latest activity sorted by date

client.getActivity({
  sort: "action_on"
});

Bookmarks

getMyBookmarks(params = {})

Get the bookmarks of the currently logged in user

Get the user's bookmarks

client.getMyBookmarks();

Collections

getCollections(params = {})

Get all available collections

client.getCollections();

getCollection(collection, params = {})

Get a single collection's info by name

client.getCollection("movies");

createCollection(data = {})

Create a new collection

client.createCollection({
  collection: "projects",
  note: "This is a new collection",
  fields: [{
    field: "id",
    type: "integer",
    datatype: "int",
    interface: "primary_key",
    primary_key: true,
    auto_increment: true,
    length: 10,
    signed: false
  }]
});

updateCollection(collection, data = {})

Update a collection's info by name

client.updateCollection("projects", {
  icon: "person"
});

deleteCollection(collection)

Delete a collection

client.deleteCollection("projects");

WARNING

This will remove the entire collection including everything in it without confirmation of safety fallbacks.


Collection Presets

createCollectionPreset(data)

Creates a new collection preset (eg bookmark / listing preferences)

client.createCollectionPreset({
  title: "My First Bookmark",
  view_query: {
    tabular: {
      fields: ["status", "datetime", "sale_amount", "tax_amount", "member"],
      sort: "-datetime"
    }
  }
});

updateCollectionPreset(primaryKey, data)

Update a collection preset by primary key

client.updateCollectionPreset(15, {
  title: "My New Bookmark Title"
});

deleteCollectionPreset()

Delete a collection preset by primary key

client.deleteCollectionPreset(15);

Extensions

getInterfaces()

Get all the available interfaces

client.getInterfaces();

getLayouts()

Get all the available layouts

client.getLayouts();

getPages()

Get all the available pages

client.getPages();

Fields

getAllFields(params = {})

Get all fields of all collections

client.getAllFields();

getFields(collection, params = {})

The the fields of a given collection

client.getFields("movies");

getField(collection, fieldName, params = {})

Get the field information for a single given field

client.getField("movies", "actors");

createField(collection, fieldInfo)

Create a new field in a given collection

client.createField("movies", {
  field: "runtime",
  type: "integer",
  datatype: "int",
  interface: "numeric"
});

updateField(collection, fieldName, fieldInfo)

Update a given field

client.updateField("movies", "runtime", { length: 10 });

updateFields(collection, fieldsInfoOrFieldNames, fieldInfo = null)

Update multiple fields at once

// Set multiple fields to the same value
client.updateFields(
  "projects",
  ["first_name", "last_name", "email"],
  { default_value: "" }
);

// Set multiple fields to different values
client.updateFields("projects", [
  { id: 14, sort: 1 },
  { id: 17, sort: 2 },
  { id: 22, sort: 3 }
]);

deleteField(collection, fieldName)

Delete a field by name

client.deleteField("movies", "runtime");

WARNING

This will remove the field from the collection including all the saved data.


Files

uploadFiles(data, onUploadProgress)

Will upload files in multipart/form-data enctype to the API. data is a JS FormData containing the files to upload.

<form id="my-form">
  <input type="file" name="file" />
</form>

<script>
const form = document.querySelector("#my-form");
const data = new FormData(form);

client.uploadFiles(data, onUploadProgress);

function onUploadProgress(progressEvent) {
  const percentCompleted = Math.round((progressEvent.loaded * 100) / progressEvent.total);

  console.log(percentCompleted + "% Done");
}
</script>

Items

updateItem(collection, primaryKey, data)

Update an item

client.updateItem("movies", 15, {
  title: "A newer hope"
});

updateItems(collection, data)

Update multiple items at once

client.updateItems("movies", [
  { id: 15, sort: 1 },
  { id: 21, sort: 2 },
  { id: 11, sort: 3 }
]);

createItem(collection, body)

Create a new item

client.createItem("movies", {
  title: "The DB of Destiny",
  runtime: 210,
  rating: 2.4
});

createItems(collection, body)

Create multiple items

client.createItems("movies", [
  {
    title: "The DB of Destiny",
    runtime: 210,
    rating: 2.4
  },
  {
    title: "Postgresalypto",
    runtime: 190,
    rating: 4.3
  }
]);

getItems(collection, params = {})

Get items from a given collection

client.getItems("movies", {
  filter: {
    runtime: {
      gt: 200
    }
  }
});

deleteItem(collection, primaryKey)

Delete an item

client.deleteItem("movies", 15);

WARNING

This doesn't perform any checks. Make sure you don't have any relations relying on this item before deleting it.


deleteItems(collection, primaryKeys)

Delete multiple items

client.deleteItems("movies", [15, 21, 35]);

WARNING

This doesn't perform any checks. Make sure you don't have any relations relying on these items before deleting them.


Listing Preferences

getMyListingPreferences(collection, params = {})

Get the listing prefernces of the current user. These are used in the Directus app to render the items in a certain way. (Eg tabular vs cards)


Permissions

getPermissions(params = {})

Get all permissions in the system (raw records).

This will retrieve all permissions for all users.

client.getPermissions();

getMyPermissions(params = {})

The the permissions that apply to the current user.

client.getMyPermissions();

createPermissions(data)

Create multiple new permissions.

client.createPermissions([
  {
    collection: "movies",
    role: 3,
    status: "released",
    create: "full",
    read: "mine",
    update: "role",
    delete: "none"
  },
  {
    collection: "movies",
    role: 2,
    status: "released",
    create: "none",
    read: "none",
    update: "none",
    delete: "full"
  }
]);

updatePermissions(data)

Update multiple permissions

client.updatePermissions([
  {
    id: 15,
    delete: "none"
  },
  {
    id: 21,
    update: "full"
  }
]);

Relations

getRelations(params = {})

Get all the Directus relations.

client.getRelations();

createRelation(data)

Create a new relationship.

client.createRelation({
  collection_many: "sales",
  field_many: "ticket",
  collection_one: "tickets"
});

updateRelation(primaryKey, data)

Update a relationship by primary key.

client.updateRelation(22, {
  field_one: "sold_tickets"
});

getCollectionRelations(collection, params = {})

Get the relationships that apply to a given collection.

client.getCollectionRelations("movies");

Revisions

getItemRevisions(collection, primaryKey, params = {})

Get all the revisions of a single item.

client.getItemRevisions("movies", 15);

revert(collection, primaryKey, revisionID)

Revert an item to a previous state based on the ID of the revision.

client.revert("movies", 15, 21);

WARNING

This doesn't take schema changes into account. Use with caution.


Roles

getRole(primaryKey, params = {})

Get a user role by primary key.

client.getRole(primaryKey, params = {})

getRoles(params = {})

Get all the user roles

client.getRoles();

updateRole(primaryKey, body)

Update a user role

client.updateRole(15, {
  name: "Interns"
});

createRole(body)

Create a new user role

client.createRole({
  name: "Project Managers",
  ip_whitelist: ["192.168.0.1"]
});

deleteRole(primaryKey)

Delete a user role

client.deleteRole(15);

WARNING

This doesn't affect the users in the role. Make sure to remove all users from this role before deleting the role. Otherwise your users will lose access to the system.


Settings

getSettings(params = {})

Get Directus' settings

client.getSettings();

Users

getUsers(params = {})

Get a list of available users in Directus

client.getUsers({
  filter: {
    status: {
      eq: "active"
    }
  }
});

getUser(primaryKey, params = {})

Get information about a single user

client.getUser(15, {
  fields: ["first_name", "last_name"]
});

getMe(params = {})

Get the currently logged in user.

client.getMe();

updateUser(primaryKey, body)

Update a user by primary key

client.updateUser(5, {
  locale: "nl-NL"
});

Server Utils

ping()

See if the server is live and reachable

client.ping();

serverInfo()

Fetches the info of the server, like php version or server type.

client.serverInfo();

getThirdPartyAuthProviders()

Get all the third party auth providers that can be used to login to the API

client.getThirdPartyAuthProviders();

Internal methods

These methods are used by all other methods listed above and aren't generally used in normal operation. You can use the following methods to make requests to custom endpoints or use HTTP methods that aren't provided by the methods above.

request(method, endpoint, params = {}, data = {}, noProject = false, headers = {})

Make a generic request to the API based on the parameters provided.

Make a post request to /update:

client.request("post", "/update");

Get the server info:

client.request("get", "/server/info", {}, {}, true);

get(endpoint, params = {})

Send a GET request to a given endpoint.

Get all movies sorted by date:

client.get("/items/movies", {
  sort: "-datetime"
});

post(endpoint, body = {}, params = {})

Send a POST request to a given endpoint.

Create a new movie only returning the ID of the newly created item

client.post(
  "/items/movies",
  { title: "A New Hope" },
  { fields: "id" }
);

patch(endpoint, body = {}, params = {})

Send a PATCH request to a given endpoint.

Update the movie with ID 5

client.patch("/items/movies/5", { title: "A Newer Hope" });

put(endpoint, body = {}, params = {})

Send a PUT request to a given endpoint.

This method isn't used by the API by default


delete(endpoint)

Send a DELETE request to a given endpoint.

Delete the movie with ID 5

client.delete("/items/movies/5");

startInterval(fireImmediately = false)

Start the token refresh interval. This will check the tokens validity every 10 seconds and will fetch a new token when the current token is about to expire.

The fireImmediately method controls whether or not to immediately try refreshing the token.

client.startInterval(true);

stopInterval()

Stops the refresh token interval

client.stopInterval();