Directus API Cheat Sheet

Last updated: 2026-04-11 Directus instance: https://db.solanasis.com Related: operations/directus-recovery.md, operations/service-inventory.md

---

Authentication Methods

Method	When to Use	How
api-cowork static token	Remote CLI (Cowork, Claude Code)	Authorization: Bearer <DIRECTUS_COWORK_TOKEN> + CF Service Token headers (CF-Access-Client-Id, CF-Access-Client-Secret)
api-admin JWT	One-time setup / admin tasks	POST /auth/login with email/password, use returned access_token
Read-only API token	Local read scripts	Authorization: Bearer <DIRECTUS_API_TOKEN>
Admin UI login	Human browser access	email/password at db.solanasis.com (OTP first)

---

Secrets Reference

Secret	Infisical Folder	Purpose
DIRECTUS_COWORK_TOKEN	/supabase/	Static token for api-cowork@solanasis.com
CF_SERVICE_TOKEN_ID	/supabase/	CF-Access-Client-Id header value
CF_SERVICE_TOKEN_SECRET	/supabase/	CF-Access-Client-Secret header value
DIRECTUS_API_TOKEN	/supabase/	Read-only API token (existing)
DIRECTUS_API_ADMIN_EMAIL	/supabase/	Admin login email
DIRECTUS_API_ADMIN_PASSWORD	/supabase/	Admin login password

All secrets injected via secret run supabase -- <command> (zero-disk, in-memory only).

---

CLI Usage (directus_cli.py)

# Preflight check
secret run supabase -- python3 supabase/directus_cli.py --check-only
 
# List contacts (JSON output)
secret run supabase -- python3 supabase/directus_cli.py --json list crm_contacts --limit 10
 
# Get a specific contact
secret run supabase -- python3 supabase/directus_cli.py get crm_contacts <uuid>
 
# Create a contact (requires --confirm)
secret run supabase -- python3 supabase/directus_cli.py create crm_contacts '{"first_name":"Jane","last_name":"Doe","email":"jane@example.com"}' --confirm
 
# Update a contact
secret run supabase -- python3 supabase/directus_cli.py update crm_contacts <uuid> '{"phone":"+1-555-0123"}' --confirm
 
# Delete a contact
secret run supabase -- python3 supabase/directus_cli.py delete crm_contacts <uuid> --confirm
 
# Dry-run (preview without changes)
secret run supabase -- python3 supabase/directus_cli.py --dry-run create crm_contacts '{"first_name":"Test"}'

---

Python Client Usage

# Remote access (from Cowork/Windows)
# Run with: secret run supabase -- python3 script.py
from supabase.directus_client import DirectusClient
 
client = DirectusClient.remote()  # Reads env vars automatically
contacts = client.get_items("crm_contacts", params={"limit": 10})
new = client.create_item("crm_contacts", {"first_name": "Test"})
client.update_item("crm_contacts", new["id"], {"last_name": "User"})
client.delete_item("crm_contacts", new["id"])
 
# Local access (from WSL on same machine)
client = DirectusClient()  # Uses localhost:8055, DIRECTUS_API_TOKEN

---

Common API Endpoints

Endpoint	Purpose	Notes
GET /items/{collection}	List items	?limit=10&offset=0&sort=-date_created
GET /items/{collection}/{id}	Get single item	?fields=id,first_name,email
POST /items/{collection}	Create item	Body: JSON object
PATCH /items/{collection}/{id}	Update item	Body: JSON with changed fields only
DELETE /items/{collection}/{id}	Delete item
GET /server/health	Health check	No auth needed
GET /users/me	Current user info	Requires auth
POST /auth/login	Get JWT	Body: {"email":"...","password":"..."}

---

CRM Collections

Primary:

• crm_contacts — contact records
• crm_deals — deal/opportunity tracking
• crm_interactions — interaction log (calls, emails, meetings)
• crm_tasks — task management

Prospects:

• prospects_foundations — foundation prospects
• prospects_fcto — fractional CTO prospects
• prospects_rehab — rehab/recovery prospects
• prospects_msp — MSP prospects

Supporting:

• crm_org_members — organization membership links
• crm_deal_stage_log — deal stage change history
• crm_deal_checklists — deal checklist items

Events:

• events — event records
• event_sources — event source tracking

Operational:

• audit_log — system audit trail
• notifications — notification records
• ops_agent_sessions — AI agent session logs
• ops_change_log — operational change log

---

Users and Roles

User	Role	Access Scope	Usage
admin@solanasis.com	Admin	Full access (UI + API)	Browser login only
api-admin@solanasis.com	API Admin	Admin via JWT	Setup tasks only
api-cowork@solanasis.com	API Cowork	Full CRUD on CRM collections, no admin/app access	Remote CLI/scripts
Read-only API role	API Read Only	Read-only on all collections	Local scripts

---

Troubleshooting

• 401 Unauthorized: Check DIRECTUS_COWORK_TOKEN is valid — regenerate via Directus admin UI if expired.
• 403 Forbidden: Check CF Service Token headers are present and correct, or check role permissions in Directus.
• Connection refused: Directus container may be down — docker ps | grep directus to verify.
• CF Access denied: Service Token may be expired (1-year expiry). Recreate in CF dashboard under Access > Service Auth.
• CORS errors: Only relevant for browser-based access. CLI/script access is not affected by CORS.
• Rate limiting: No rate limits configured on Directus itself. CF WAF rules may apply.