Getting Started

Use the API

Get started with Directus APIs. Learn to interact with collections, fetch, and create data.

This guide will cover interacting with collections in Directus via the REST APIs automatically created on your behalf. You will fetch and create data, and make your first request with the Directus SDK.

You can use a visual API testing tool like Postman or Hoppscotch, a terminal-based based tool like curl or HTTPie, or make HTTP requests directly in a script written in your programming language of choice.

Before You Start

You will need a Directus project.

Everything you need to start building. Provisioned in 90 seconds.

Create a posts collection with at least a title and content field. Follow the Data Modeling quickstart to learn more.

You also need an admin static token. In the Data Studio, go to your user detail page. Create a new token, take note of it, and then save.

Read more about tokens and cookies in Directus Auth.

Fetching Data

Open your terminal and run the following command to read items from the posts collection.

Terminal
curl \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--url 'https://directus.example.com/items/posts'
Replace values
  • The Base URL (https://directus.example.com) must be replaced with your project URL.
  • In the Authorization Header, replace YOUR_ACCESS_TOKEN with your admin static token.
  • If you used a different collection, replace posts with the name of the collection.

Directus will respond with an array of items. The default limit is 100, so if there are more than 100 items, you must either provide a higher limit or request a second page.

Using Query Parameters

You can use any of the global query parameters to change the data that is returned by Directus.

Terminal
curl \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --url 'https://directus.example.com/items/posts?filter[status][_eq]=published&fields=id,title'

This request will only show items with a status value of published, and only return the id and title fields.

See all available query parameters in Directus.

Creating Data

All collections are given consistent endpoints. By sending a POST request to /items/posts with an object containing properties in the collection, a new item will be created.

Terminal
curl \
    --request POST \
    --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
    --header 'Content-Type: application/json' \
    --data '{ "title": "Hello Universe!" }' \
    --url 'https://directus.example.com/items/posts'

Next Steps

All endpoints in Directus are documented in our API Reference, which also shows all expected parameters and properties in the payload. The API reference shows examples using the REST API, GraphQL API, and the Directus SDK.

Explore the Directus API Reference.