Skip to main content

​
Introduction

The Genie Helper API provides programmatic access to core platform features including:
  • User registration and authentication
  • Encrypted credential storage (platform connections, download credentials, sessions)
  • Media job queue management
  • AI-powered caption generation
  • Genie AI agent chat interface
All endpoints are designed for server-to-server integration and mobile/web clients authenticated via Directus JWT.

​
Base URLs

AnythingLLM Server (API endpoints) 
http://localhost:3001/api
Default port: 3001 (configurable via SERVER_PORT env var) Directus Backend 
http://127.0.0.1:8055
Default port: 8055 (configured via DIRECTUS_URL env var)

​
Authentication Methods

Genie Helper uses multiple authentication strategies depending on the endpoint:

​
1. Directus JWT (User Authentication)

Most user-facing endpoints require a Directus JWT token obtained via login: 
curl -X POST http://127.0.0.1:8055/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"password"}'
Response: 
{
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "..."
  }
}
Include the access token in requests: 
Authorization: Bearer <access_token>

​
2. Shared Secret (Server-to-Server)

Internal endpoints like /api/credentials/store and /api/credentials/reveal use a shared secret header: 
X-RBAC-SYNC-SECRET: <RBAC_SYNC_WEBHOOK_SECRET>
This secret is configured in the .env file and should never be exposed to clients.

​
3. Admin Token (Proxied Operations)

Some endpoints use the Directus admin token server-side to perform privileged operations (e.g., user registration). This token is never exposed to clients.

​
Rate Limiting & Tiers

Certain operations (e.g., media job enqueuing) enforce subscription tier limits via the canPerform() validator. Responses include: 
{
  "error": "tier_limit_reached",
  "reason": "limit_reached",
  "message": "You have reached your plan limit for this feature. Upgrade to continue."
}

​
Error Handling

All endpoints return consistent error structures: Success: 
{
  "ok": true,
  "success": true,
  "...": "endpoint-specific fields"
}
Error: 
{
  "ok": false,
  "success": false,
  "error": "Error message description"
}
Common HTTP status codes:
  • 200 - Success
  • 400 - Bad request (missing required fields)
  • 401 - Unauthorized (invalid/missing token)
  • 403 - Forbidden (tier limit or permissions)
  • 404 - Not found
  • 500 - Internal server error
  • 502 - Upstream service error (Ollama, Directus)

​
CORS & Headers

The API server is configured with permissive CORS (origin: true) for development. All endpoints accept JSON bodies: 
Content-Type: application/json

​
Next Steps

Authentication

Learn about Directus JWT flows and admin tokens

Credentials API

Encrypt and decrypt platform credentials

Queue Management

Manage BullMQ media job queues

Captions

Generate AI-powered social media captions

Genie Chat

Stream AI agent responses via SSE

Build docs developers (and LLMs) love

Get started for freeTalk to us