Own your content — a headless CMS behind your site
In this chapter you’ll explore Directus, a headless content management system that lets you own and structure your data while keeping it separate from the presentation layer of your site. You’ll see how Directus stores content in a database, provides an intuitive API for retrieving that content, and offers a flexible admin interface for non‑technical editors. By the end you’ll understand the core concepts behind headless CMS architecture, how Directus fits into modern web workflows, and what steps are needed to set up and start using it as the backbone of your digital projects.
It stores your content in a database and provides a flexible, user‑friendly interface plus API endpoints so you can retrieve and update data without coupling to a front‑end framework.
A headless approach separates content storage from presentation, giving you freedom to deliver the same data across multiple platforms while keeping full control over your content architecture.
The API Docs button reveals the generated endpoint URL for a collection.
Show that separating content from presentation lets multiple front‑ends share the same data through one API
GET /items/articles URL and run it with curl in a terminalThe Save action stores edits in Directus before they are exported and committed to the content repository.
Export edited content from Directus and commit it to the content repository so the next static build includes the change
A docker-compose.yml file defines the services, environment variables and persistent storage needed to launch Directus locally.
Get a Directus instance running locally with Docker Compose, using persistent storage, so you have a real instance for the rest of this chapter instead of reading about one.
docker compose up with a SECRET, a DB_CLIENT/DB_FILENAME pair and a PUBLIC_URL gets a real, persistent Directus instance running on port 8055 — no license key needed for self‑hosted Core‑tier useA Select (Dropdown) field provides a closed list of allowed values for a collection attribute.
Create a collection with fields typed and constrained tightly enough that a colleague who has never seen a database can edit an entry without breaking anything downstream.
article.The Roles & Permissions editor lets you assign Create/Read/Update/Delete rights per collection and field for a specific role.
Create a role scoped to only the collections and actions one type of user actually needs, so a content editor cannot accidentally reach Settings, Users, or a collection outside their job.
The /items/
Pull real content out of your Directus instance over both the REST and GraphQL APIs so you can see exactly what a consumer receives.
/graphql./items/) and GraphQL (/graphql, plus /graphql/system for system data) out of the box, with fields on REST letting you limit public exposureThe Monospace Sustainable Core License (MSCL‑1.0‑GPL) governs Directus’s free usage terms and upgrade conditions.
State the exact licence Directus uses, what “free” entails, and how revenue or headcount thresholds affect pricing
A decision matrix evaluates editor count, API consumption, and permission granularity to justify a headless CMS.
Determine whether the project’s content workflow justifies adding Directus instead of using markdown files.
16 outcomes in all — one per recipe below.
Want a simple CMS backend DB
A CMS database relies on two core tables: users (storing ID, username, email, and role) and content (storing ID, title, body, status, and author ID). Linking them via a foreign key ensures every piece of content is tied to a specific creator, while the role and status fields enable editorial workflows and permission checks without complex joins. This normalized structure keeps data consistent and scales cleanly as you add more content types.
Need front‑end apps to add, edit or delete site content and images
A headless or traditional CMS backend communicates through standardized HTTP methods mapped to specific endpoints. Using /api/content for listing, creating, updating, and deleting content, plus /api/media/upload for assets, creates a predictable interface that frontends or mobile apps can consume. This separation of concerns allows the presentation layer to change independently while the data layer remains stable.
Editors can’t access admin functions
Content platforms are frequent targets for injection and unauthorized access, so security must be baked into the application layer. Implementing role-based access control (RBAC) with JSON Web Tokens (JWT) ensures only authorized users can modify content, while strict input validation and sanitization block SQL injection and cross-site scripting (XSS). Coupled with HTTPS and activity logging, this creates a defense-in-depth posture that protects both data and infrastructure.
Move your Webflow blog to a new CMS
The Directus MCP server exposes CMS operations as standardized tool calls that an AI agent can execute. By connecting Cursor to both the Webflow and Directus MCP servers, the agent can read legacy posts, map them to a Directus template, and push them into the correct collection with category metadata. This works because MCP abstracts the API complexity, allowing the LLM to handle extraction, transformation, and publishing autonomously.
Paste a URL or draft in your editor
Instead of manually writing and uploading content, you can drop URLs or paste draft text directly into Cursor and ask the AI agent to draft a post. The agent uses the Directus MCP to publish the content to the CMS, automatically attaching category tags and SEO metadata. This works because the MCP acts as a bridge between the IDE and the CMS, letting the LLM handle formatting, categorization, and API submission in one workflow.
Need a full CMS set up from an empty instance
The Directus Template CLI automates the tedious setup of schemas, permissions, and example data by pushing a pre-configured project structure directly into a fresh Directus instance. Instead of manually creating collections, dashboards, and flows, developers can instantly load a production-ready baseline to study, deconstruct, and build upon. The tool works by authenticating via a static admin token and executing a series of API calls to populate the database and UI configuration.
Public API requests should never modify data
The public role dictates what data is exposed without login, defaulting to no access for all collections. Keeping it restricted prevents unauthorized data modification, as unauthenticated requests should only retrieve safe, read-only content. By explicitly locking Create, Update, and Delete operations, you eliminate accidental data corruption from anonymous API calls.
Need to hide draft content from a role
Directus allows granular rules at the item level, letting you control exactly which records a role can access. By applying a rule like status equals published, you ensure that draft or review-stage content remains invisible to that role, even if they have general read access to the collection. This keeps the API response lean and prevents internal workflow states from leaking.
Trying to edit someone else’s post
Directus supports dynamic variables like current.user.id that reference the logged-in user session. By applying this variable to a custom rule (e.g., author.id equals current.user.id), you enforce row-level security where users can only modify records they personally created. This eliminates the need for manual access lists and scales automatically as your team grows.
Confidential columns hidden from non‑admin roles
Beyond controlling which records a role sees, Directus lets you hide individual fields at the permission level. This strips identifiers, internal notes, or metadata from both the app UI and API responses for non-admin roles, reducing data exposure without altering the underlying database schema.
Need to manually set creator ID or status on new items
Presets let you define default values that automatically apply when a role creates or updates an item. This enforces data consistency by automatically tagging new records with the creator's ID or setting a default status, removing manual input steps and preventing human error during content entry.
Need a UI for existing SQL tables without altering the schema
Directus does not migrate or alter your existing SQL schema. Instead, it introspects the database architecture and mirrors it into its Data Studio interface. This lets non-technical users manage data through a UI while developers retain full control over the underlying tables and can bypass the middleware with direct SQL queries.
Want a tailored input form without coding
Directus separates data structure from user interface. You can define fields in the data model, then independently configure how they appear in the editor using the interface, display, and validation tabs. This allows you to create tailored input forms like auto-slug generators or WYSIWYG editors without writing code.
When a new article gets published
Directus Flows acts as an internal automation engine similar to Zapier. You define a trigger like an item creation event, chain operations like sending an email, and inject dynamic variables from the trigger into the operation payloads. This runs server-side without external dependencies.
Only need a few columns plus their related records
Directus auto-generates REST and GraphQL APIs for every collection. You can optimize API payloads by using the fields query parameter to request only needed columns, and use dot notation or wildcards to fetch nested relational data in a single request, avoiding multiple round trips.
Public endpoints hide draft pages
Directus uses a role-based access control system where permissions are granular per collection and operation. By creating a static token for an admin user, you can bypass public restrictions and access draft or unpublished data programmatically, while keeping public endpoints locked down by default.
The same set on /recipes, filtered by tool and role.
Ask, share, or report — over on the Heidelberg AI community forum.