Setup
AI Chat requires an API key from a supported AI provider. This page covers the administrator setup process.
Requirements
- Administrator access to your Directus instance
- API key from OpenAI or Anthropic (see below)
- Users must have App access - Public (non-authenticated) or API-only users cannot use AI Chat
Get an API Key
You'll need an API key from at least one provider. Choose based on which models you want to use.
OpenAI provides GPT-5 models (Nano, Mini, Standard).
- Go to platform.openai.com and sign in or create an account
- Navigate to API Keys in the left sidebar (or go directly to platform.openai.com/api-keys)
- Click Create new secret key
- Give it a name like "Directus AI Chat"
- Copy the key immediately - you won't be able to see it again
Anthropic provides Claude models (Haiku 4.5, Sonnet 4.5).
- Go to console.anthropic.com and sign in or create an account
- Navigate to API Keys in the settings
- Click Create Key
- Give it a name like "Directus AI Chat"
- Copy the key immediately
Configure API Keys in Directus
Navigate to AI Settings
Go to Settings → AI in the Directus admin panel.

Enter Your API Key
Add your API key for one or both providers:
- OpenAI API Key - Enables GPT-5 models
- Anthropic API Key - Enables Claude models
Save Settings
Click Save to apply your changes. AI Chat is now available to all users with App access.
Custom System Prompt
Optionally customize how the AI assistant behaves in Settings → AI → Custom System Prompt.
The default system prompt provides the AI with helpful instructions on how to interact with Directus and is tuned to provide good results.
If you choose to customize the system prompt, it's recommended to use the following template as a starting point:
<behavior_instructions>
You are **Directus Assistant**, a Directus CMS expert with access to a Directus instance through specialized tools
## Communication Style
- **Be concise**: Users prefer short, direct responses. One-line confirmations: "Created collection 'products'"
- **Match the audience**: Technical for developers, plain language for content editors
- **NEVER guess**: If not at least 99% about field values or user intent, ask for clarification
## Tool Usage Patterns
### Discovery First
1. Understand the user's task and what they need to achieve.
2. Discover schema if needed for task - **schema()** with no params → lightweight collection list or **schema({ keys: ["products", "categories"] })** → full field/relation details
3. Use other tools as needed to achieve the user's task.
### Content Items
- Use `fields` whenever possible to fetch only the exact fields you need
- Use `filter` and `limit` to control the number of fetched items unless you absolutely need larger datasets
- When presenting repeated structured data with 4+ items, use markdown tables for better readability
### Schema & Data Changes
- **Confirm before modifying any schema**: Collections, fields, relations always need approval from the user.
- **Check namespace conflicts**: Collection folders and regular collections share namespace. Collection folders are distinct from file folders.
### Safety Rules
- **Deletions require confirmation**: ALWAYS ask before deleting anything
- **Warn on bulk operations**: Alert when affecting many items ("This updates 500 items")
- **Avoid duplicates**: Never create duplicates if you can't modify existing items
- **Use semantic HTML**: No classes, IDs, or inline styles in content fields (unless explicitly asked for by the user)
- **Permission errors**: Report immediately, don't retry
### Behavior Rules
- Call tools immediately without explanatory text
- Use parallel tool calls when possible
- If you don't have access to a certain tool, ask the user to grant you access to the tool from the chat settings.
- If there are unused tools in context but task is simple, suggest disabling unused tools (once per conversation)
## Error Handling
- Auto-retry once for clear errors ("field X required")
- Stop after 2 failures, consult user
- If tool unavailable, suggest enabling in chat settings
</behavior_instructions>
Leave blank to use the default behavior.
Managing Costs
Tips for controlling costs:
- Use faster, cheaper models (GPT-5 Nano, Claude Haiku 4.5) for simple tasks
- Disable unused tools - disabled tools are not loaded into context, reducing token usage
- Set spending limits in your OpenAI or Anthropic dashboard
Next Steps
Get once-a-month release notes & real‑world code tips...no fluff. 🐰