Eve library

Yemaya Domain API Reference

Guide

Revision 1

On this page

Yemaya is the creative production platform of the Oshun monorepo. It provides a single unified API service built with Hono (OpenAPIHono) that covers the full lifecycle of movie and game creation -- from scriptwriting and asset management to AI generation, virtual production, and engine integrations.

Service Framework Default Port Documentation UI
api OpenAPIHono 3000 /docs, /reference, /playground

The API is versioned under /v1 and publishes a machine-readable OpenAPI 3.1 specification at /openapi.json.


Common Patterns#

Authentication#

Two authentication mechanisms are supported:

  1. JWT Bearer Token -- obtained via POST /v1/auth/login or OAuth flow.
    text
    Authorization: Bearer <jwt_token>
    
  2. API Key -- for server-to-server integration.
    text
    X-API-Key: <api_key>
    

Error Handling (RFC 7807 Problem Details)#

All errors use the RFC 7807 Problem Details format:

json
{
  "type": "https://api.yemaya.io/problems/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "The requested resource GET /v1/projects/xxx was not found",
  "instance": "https://api.yemaya.io/v1/projects/xxx",
  "requestId": "req_abc123",
  "timestamp": "2026-02-14T12:00:00.000Z"
}

Rate Limiting#

  • Authenticated users: 1000 requests/minute
  • Unauthenticated: 60 requests/minute

Response headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Pagination#

All list endpoints support:

Parameter Default Max Description
page 1 -- Page number
limit 20 100 Items per page

Response envelope:

json
{
  "data": [...],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8,
    "hasMore": true
  }
}

API Versioning#

Versioning is supported via:

  • Path prefix: /v1/... (primary)
  • Header: X-API-Version: 1.0

Deprecated endpoints include Deprecation and Sunset response headers.

Input Sanitization#

All /v1/* routes pass through XSS, SQL injection, and command injection sanitization middleware. Asset upload routes have additional metadata sanitization.


Route Groups (44 Groups)#

The Yemaya API mounts 44 route groups under /v1. Below is the complete list organized by functional area, with the prefix each router is mounted at.

Core Platform#

# Mount Path Router Purpose
1 /v1/auth authRouter Login, signup, OAuth, API keys, sessions
2 /v1/users usersRouter User accounts, profile, preferences, activity
3 /v1/organizations organizationsRouter Orgs, members, teams, invitations, audit logs
4 /v1/admin adminRouter System admin, user admin, moderation, flags
5 /v1/versions versioningRouter API version info, migration guides

Project Management#

# Mount Path Router Purpose
6 /v1/projects projectsRouter Project CRUD, members, comments, activity
7 /v1/projects/:projectId/assets assetsRouter Asset upload, folders, versions
8 /v1/scripts scriptsRouter Scripts, scenes, elements, story beats
9 /v1/characters charactersRouter Characters, relationships, groups
10 /v1/worlds worldsRouter Worlds, locations, timeline, rules, cultures
11 /v1/storyboards storyboardsRouter Storyboards, panels, annotations, layers

Production Scheduling#

# Mount Path Router Purpose
12 /v1/schedules schedulesRouter Schedules, milestones, items, resources, calendar, conflicts
13 /v1/schedules scheduleOptimizationRouter AI schedule optimization, critical path, suggestions
14 /v1/schedules scheduleSharingRouter Export (PDF, CSV, ICS, XLSX, HTML, XML), share links
15 /v1/crew crewRouter Crew management, skills, availability, matching
16 /v1/call-sheets callSheetsRouter Call sheet generation, distribution, export
17 /v1/locations locationRouter Location scouting, permits, weather, maps

Budget & Finance#

# Mount Path Router Purpose
18 /v1/budgets budgetsRouter Budget CRUD, categories, expenses, POs, invoices
19 /v1/budget-templates budgetTemplatesRouter Industry templates, custom templates, import/export
20 /v1/budgets budgetLineItemsRouter Line items, variance, forecasting, bulk ops
21 /v1/budgets costPredictionRouter ML cost prediction, trend analysis, benchmarks
22 /v1/budgets varianceTrackingRouter EVM metrics, thresholds, alerts, approvals
23 /v1/currency multiCurrencyRouter Exchange rates, conversions, FX impact, hedges

Collaboration#

# Mount Path Router Purpose
24 /v1/collaboration collaborationRouter Sessions, threads, reviews, locks, presence, sharing

AI & Generation#

# Mount Path Router Purpose
25 /v1/ai aiGenerationRouter Text, image, audio, 3D, code, embeddings
26 /v1/3d threeDGenerationRouter AI 3D model generation (Rodin, Meshy, Tripo)
27 /v1/splat gaussianSplattingRouter Capture, training, rendering, export
28 /v1/procedural houdiniRouter Terrain, city, biome, HDA management
29 /v1/agents agentManagementRouter Agent registration, tasks, pools, messaging
30 /v1/audio audioRouter Music gen, voice synthesis, SFX, DAW, MIDI
31 /v1/video videoRouter Video gen, editing, VFX, rendering, NLE

Engine Integrations#

# Mount Path Router Purpose
32 /v1/virtual-production virtualProductionRouter Camera tracking, LED wall, stage calibration, compositing
33 /v1/xr xrRouter XR device detection, sessions, spatial anchors, hand tracking
34 /v1/blender blenderRouter Scene, objects, mesh, modifiers, materials, rendering
35 /v1/unreal unrealRouter Actors, assets, blueprints, materials, landscapes, sequencer
36 /v1/godot godotRouter Scenes, nodes, scripts, 2D/3D, physics, signals
37 /v1/gameplay gameplayRouter Combat, inventory, saves, progression, AI behavior
38 /v1/npcs npcRouter LLM NPCs, personality, memory, dialogue, behavior

Infrastructure#

# Mount Path Router Purpose
39 /v1/plugins pluginsRouter Plugin installation, hooks, marketplace
40 /v1/webhooks webhooksRouter Event subscriptions, deliveries, statistics
41 /v1/search searchRouter Unified search, saved searches, autocomplete
42 /v1/analytics analyticsRouter Metrics, events, funnels, cohorts, dashboards
43 /v1/gpu-jobs gpuJobsRouter GPU compute job management and monitoring
44 /ws wsRouter WebSocket real-time events

Key Endpoint Details#

Authentication (/v1/auth)#

Method Path Description
POST /v1/auth/login Login with email/password
POST /v1/auth/signup Register a new account
POST /v1/auth/logout Invalidate current session
POST /v1/auth/refresh Refresh JWT token
GET /v1/auth/oauth/:provider Start OAuth flow
GET /v1/auth/oauth/:provider/callback OAuth callback
POST /v1/auth/api-keys Create an API key
GET /v1/auth/api-keys List API keys
DELETE /v1/auth/api-keys/:id Revoke an API key

Projects (/v1/projects)#

Method Path Description
GET /v1/projects List projects
POST /v1/projects Create project
GET /v1/projects/:id Get project
PUT /v1/projects/:id Update project
DELETE /v1/projects/:id Delete project
GET /v1/projects/:id/members List members
POST /v1/projects/:id/members Add member
DELETE /v1/projects/:id/members/:userId Remove member
GET /v1/projects/:id/comments List comments
POST /v1/projects/:id/comments Add comment
GET /v1/projects/:id/activity Activity feed

Assets (/v1/projects/:projectId/assets)#

Method Path Description
GET /v1/projects/:projectId/assets List assets
POST /v1/projects/:projectId/assets Upload/create asset
GET /v1/projects/:projectId/assets/:id Get asset
PUT /v1/projects/:projectId/assets/:id Update asset
DELETE /v1/projects/:projectId/assets/:id Delete asset
GET /v1/projects/:projectId/assets/:id/versions List versions
POST /v1/projects/:projectId/assets/:id/versions Upload new version
GET /v1/projects/:projectId/assets/folders List folders
POST /v1/projects/:projectId/assets/folders Create folder

AI Generation (/v1/ai)#

Method Path Description
POST /v1/ai/text/generate Generate text (Claude, GPT)
POST /v1/ai/images/generate Generate images (DALL-E, SD)
POST /v1/ai/audio/generate Generate audio (ElevenLabs)
POST /v1/ai/3d/generate Generate 3D models
POST /v1/ai/code/generate Generate code
POST /v1/ai/embeddings Create vector embeddings
GET /v1/ai/jobs List async generation jobs
GET /v1/ai/jobs/:id Get job status
GET /v1/ai/templates List prompt templates
POST /v1/ai/templates Create prompt template
GET /v1/ai/usage Get usage statistics
GET /v1/ai/providers List available AI providers

WebSocket Events (/ws)#

The WebSocket endpoint at /ws provides real-time streaming for:

  • Generation Events -- 3D generation progress, training progress, render progress
  • Collaboration Events -- Lock/unlock notifications, edit sync, presence updates, cursor tracking
  • Pipeline Events -- Phase completion, quality gate results, agent activity, error notifications

Clients connect via standard WebSocket upgrade and receive JSON-framed events.

Health & Metrics#

Method Path Description
GET /health Basic health check
GET /health/ready Readiness with DB, cache, storage
GET /health/live Liveness probe
GET /metrics JSON or Prometheus metrics
GET /metrics/validation Benchmark validation results

Documentation#

Path Description
/openapi.json Machine-readable OpenAPI 3.1 specification
/docs Swagger UI
/reference Scalar API Reference (modern interactive)
/playground API Playground for testing requests

Security Middleware Stack#

Requests pass through the following middleware chain (in order):

  1. Request ID -- Generates X-Request-ID for tracing
  2. Request Context -- Async local storage for deep access
  3. Performance Metrics -- P95 tracking (target: 100ms)
  4. Problem Details Error Handler -- RFC 7807
  5. Secure Headers -- CSP, HSTS, X-Frame-Options, etc.
  6. CORS -- Origin whitelist with dev mode bypass
  7. Logger -- Structured logging (non-production)
  8. Compression -- gzip response compression
  9. Timing -- Server-Timing header
  10. Input Sanitization -- XSS, SQLi, command injection protection
  11. Asset Metadata Sanitization -- Upload-specific protection
  12. Rate Limiting -- Per-user/IP with Redis backing
  13. API Versioning -- Path and header-based version resolution