Use the API
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.
Fetching Data
Open your terminal and run the following command to read items from the posts
collection.
curl \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--url 'https://directus.example.com/items/posts'
- 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.
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.
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.
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.