REST API Overview

Introduction to the Directus REST API

Directus provides a comprehensive REST API that instantly layers on top of any SQL database. The API follows RESTful principles and returns JSON responses.

Base URL

All API requests should be made to:

http://your-directus-instance.com

API Versioning

The Directus API does not use versioning in the URL. The platform maintains backward compatibility and uses a rolling release cycle.

Response Format

All successful responses return a JSON object with a data property:

{
  "data": {
    // Response data here
  }
}

HTTP Methods

The API uses standard HTTP methods:

• GET - Retrieve resources
• POST - Create new resources
• PATCH - Update existing resources
• DELETE - Delete resources

Authentication

The API supports multiple authentication methods:

• Static Tokens - For server-to-server communication
• Temporary Tokens - JWT tokens from login
• SSO - OAuth, OpenID, SAML, LDAP

See the Authentication page for details.

Query Parameters

Directus supports powerful query parameters for all collection endpoints:

Filtering

Filter items using comparison operators:

GET /items/articles?filter[status][_eq]=published
GET /items/articles?filter[views][_gte]=1000

Available operators: _eq, _neq, _lt, _lte, _gt, _gte, _in, _nin, _null, _nnull, _contains, _ncontains, _starts_with, _ends_with, _between, _nbetween

Sorting

Sort results by one or more fields:

GET /items/articles?sort=title
GET /items/articles?sort=-date_created
GET /items/articles?sort=status,-date_created

Prefix with - for descending order.

Limiting & Pagination

Control the number of items returned:

GET /items/articles?limit=10
GET /items/articles?limit=10&offset=20
GET /items/articles?page=3&limit=10

Field Selection

Request specific fields:

GET /items/articles?fields=id,title,author.name
GET /items/articles?fields=*,author.*

Search

Full-text search across fields:

GET /items/articles?search=directus

Aggregation

Get aggregate values:

GET /items/articles?aggregate[count]=id
GET /items/articles?aggregate[avg]=rating
GET /items/articles?aggregate[sum]=views

Available functions: count, countDistinct, sum, sumDistinct, avg, avgDistinct, min, max

Rate Limiting

API requests are rate-limited to prevent abuse. Default limits:

• 100 requests per second per IP
• 1000 requests per minute per IP

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1620000000

Error Responses

Errors return appropriate HTTP status codes with a JSON error object:

{
  "errors": [
    {
      "message": "You don't have permission to access this.",
      "extensions": {
        "code": "FORBIDDEN"
      }
    }
  ]
}

Common status codes:

• 400 - Bad Request (invalid syntax)
• 401 - Unauthorized (authentication required)
• 403 - Forbidden (insufficient permissions)
• 404 - Not Found
• 422 - Unprocessable Entity (validation errors)
• 500 - Internal Server Error

CORS

CORS can be configured via environment variables:

CORS_ENABLED=true
CORS_ORIGIN=*
CORS_METHODS=GET,POST,PATCH,DELETE
CORS_ALLOWED_HEADERS=Content-Type,Authorization
CORS_EXPOSED_HEADERS=Content-Range
CORS_CREDENTIALS=true
CORS_MAX_AGE=86400

Next Steps

Authentication

Learn about authentication methods

Items

Work with collection items

Files

Manage files and assets

Users

Manage users and authentication