Directus Getting Started: Quickstart Guide (2026)

Getting started overview

This guide outlines the steps to get started with Directus, focusing on account creation, API key generation, and executing a first API request. Directus provides both a cloud-hosted service and an open-source, self-hostable platform for managing data through a headless CMS architecture. The core of Directus involves connecting to a SQL database, which it then wraps with a real-time REST and GraphQL API, alongside an administrative application for data management (Directus documentation overview).

The process generally involves setting up a Directus instance, defining a data model within the Directus application, obtaining necessary API credentials, and then making a request to interact with the data. Directus supports various SQL databases, including PostgreSQL, MySQL, SQLite, Oracle, and Microsoft SQL Server (Directus getting started guide).

Quick Reference Table

Create an account and get keys

To begin, you need a running Directus instance. You have two main options:

1. Directus Cloud: This is the quickest way to get started. You can sign up for a free Developer tier which provides a managed Directus instance. During signup, you'll specify a project name, which forms the base URL for your API (e.g., https://your-project.directus.app). After creating your account, you'll be prompted to set up your initial admin user and connect to a database, though Directus Cloud often provisions a database for you by default (Directus Cloud documentation).
2. Self-Hosting: For full control and custom environments, you can self-host Directus. This requires setting up a server, installing Directus via npm, Docker, or other methods, and configuring it to connect to your preferred SQL database. The Directus self-hosting installation guide provides detailed instructions for various deployment scenarios, including using Docker Compose for a quick local setup.

API Key Generation

Once your Directus instance is running and you've logged into the Admin App, you'll need to create credentials to interact with the API. Directus supports several authentication methods, including:

• Static Tokens: These are long-lived tokens suitable for server-to-server communication or applications where user login isn't required for every request. To create one, navigate to Settings > Access Tokens in the Directus Admin App. Click 'Create Token', give it a descriptive name, and assign it appropriate permissions. Make sure to copy the token immediately, as it will not be shown again (Directus static tokens guide).
• OAuth2 Flow: For user-facing applications, Directus can act as an OAuth2 provider, allowing users to log in and obtain temporary access tokens. This involves configuring an OAuth2 client within Directus. The OAuth 2.0 Authorization Framework is an industry-standard protocol for delegated authorization (OAuth 2.0 specification overview).
• Session-based Authentication: This is typically used by the Directus Admin App itself, where users log in with email/password and receive a session cookie. While possible for custom frontends, static tokens or OAuth are often preferred for API interactions beyond the Admin App.

For your first request, a Static Token is the simplest and most direct method to get started.

Your first request

Before making your first request, you need to create a data collection in your Directus instance. This serves as the endpoint for your API calls.

1. Create a Collection: In the Directus Admin App, go to Data Studio > Collections. Click the 'Create Collection' button. Give it a singular name (e.g., product) and a plural name (e.g., products). Directus will automatically generate a table in your connected database. For this example, let's create a collection named articles.
2. Add Fields: To the articles collection, add a few fields. For instance, add a 'Text Input' field named title and another 'Text Input' field named content. Set the title field as required.
3. Add Content: Navigate to the articles collection in the Data Studio and add a new item. Enter a title and some content, then save it. This provides data for your first fetch request.
4. Set Permissions: By default, public access to new collections might be restricted. Go to Settings > Role & Permission, select the Public role. Under your articles collection, enable 'Read' permissions for the Public role. This allows unauthenticated requests to retrieve data from this collection (Directus roles and permissions guide).
5. Make the Request: Replace YOUR_DIRECTUS_URL with your actual Directus instance URL (e.g., https://your-project.directus.app) and YOUR_STATIC_TOKEN with the token you generated. If you enabled Public Read access for the collection, the Authorization header might not be strictly necessary for a GET request, but it's good practice for authenticated endpoints.

Example: Fetching all items from a Collection (REST API)

This example uses cURL, a command-line tool for making HTTP requests (cURL project website). You can execute this in your terminal.

curl -X GET \
  "YOUR_DIRECTUS_URL/items/articles" \
  -H "Authorization: Bearer YOUR_STATIC_TOKEN"

If successful, this will return a JSON array of items from your articles collection, including the one you added.

Example: Creating an Item (REST API)

To create a new item, you'll use a POST request with a JSON body.

curl -X POST \
  "YOUR_DIRECTUS_URL/items/articles" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_STATIC_TOKEN" \
  -d '{ "title": "My New Article", "content": "This is the content of my new article." }'

A successful response will include the details of the newly created item, including its ID.

Example: Fetching with GraphQL

Directus also provides a GraphQL API. The endpoint is typically /graphql. Here's a cURL example for fetching articles using GraphQL:

curl -X POST \
  "YOUR_DIRECTUS_URL/graphql" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_STATIC_TOKEN" \
  -d '{ "query": "query { articles { id title content } }" }'

This query requests the id, title, and content for all items in the articles collection (GraphQL specification).

Common next steps

After successfully making your first requests, consider these common next steps to further develop your Directus project:

• Explore Data Modeling: Directus's strength lies in its flexible data modeling. Experiment with different field types (e.g., rich text, image, relation fields) and create more complex data structures (Directus data model reference). Define relationships between collections to build interconnected content.
• Understand Permissions and Roles: Fine-tune access control by creating custom roles and configuring granular permissions for collections and fields. This is crucial for securing your data and defining user access levels (Directus roles and permissions management).
• Utilize the JavaScript SDK: For frontend or Node.js applications, the Directus JavaScript SDK can simplify interactions with the API, handling authentication, pagination, and data manipulation more efficiently than raw HTTP requests.
• Webhooks and Flows: Implement webhooks to trigger actions in external systems when data changes in Directus. Explore Directus Flows for creating custom internal automation and business logic within the platform (Directus Flows documentation).
• Authentication Methods: Beyond static tokens, explore OAuth2 for user login flows or integrate with external authentication providers if needed for your application's user base.
• API Reference: Consult the comprehensive Directus API Reference for detailed information on all available endpoints, parameters, and response structures for both REST and GraphQL APIs.
• Deployment Strategies: If you started with Directus Cloud, consider optimizing your deployment for production or exploring self-hosting options for specific requirements. Kubernetes is a common platform for deploying containerized applications like Directus (Kubernetes official documentation).

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting tips:

• Check your Directus URL: Ensure the URL in your request (e.g., YOUR_DIRECTUS_URL/items/articles) is correct and points to your running Directus instance. For Cloud users, this is typically https://your-project.directus.app.
• Verify Static Token: Double-check that the YOUR_STATIC_TOKEN is correctly copied and included in the Authorization: Bearer header. Tokens are case-sensitive and must be exact. Ensure there are no leading/trailing spaces.
• Review Permissions: The most frequent cause of 403 Forbidden errors is incorrect permissions. Go to Settings > Role & Permission in the Directus Admin App. For the role associated with your token (or the Public role if not using a token), ensure 'Read' access is granted to the collection and fields you are trying to access. For POST requests, you'll need 'Create' permissions.
• Content-Type Header for POST/PUT: When sending data in the request body (e.g., for POST or PUT requests), ensure you include the Content-Type: application/json header. Without it, Directus may not correctly parse your request body.
• Collection Name Pluralization: The REST API often expects the plural form of your collection name (e.g., /items/articles for a collection named article). Verify the exact endpoint path in your Directus documentation or by inspecting network requests from the Admin App.
• Network Issues: Ensure your local machine can reach the Directus instance. If self-hosting, check firewall rules or server logs for connection errors.
• Directus Logs: If you are self-hosting, check your Directus server logs for more detailed error messages. For Directus Cloud, you might find some operational insights within your project dashboard or by contacting support.
• GraphQL Query Syntax: If using GraphQL, ensure your query is syntactically correct and matches the schema generated by Directus. The GraphQL endpoint typically provides an interactive playground (like GraphiQL) that can help validate queries (Directus GraphQL reference).