Use the API

:video-embed{video-id="4cc18530-ba2a-44f3-bb2e-2bfe4ad024d5"}

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.

:partial{content="quickstart-making-calls"}

Before You Start

You will need a Directus project.

:cta-cloud

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.

::callout{icon="material-symbols:menu-book-outline" color="primary" to="/guides/auth/tokens-cookies"} 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.

curl \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--url 'https://directus.example.com/items/posts'

::callout{icon="material-symbols:info-outline"} 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.

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.

::callout{icon="material-symbols:menu-book-outline" color="primary" to="/guides/connect/query-parameters"} 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.

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

:video-embed{video-id="0cbf2b23-545e-4ea7-ae45-47707292caec"}

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.

::callout{icon="material-symbols:code-blocks-rounded" color="green" to="/api"} Explore the Directus API Reference. ::