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:
JWT Bearer Token -- obtained via POST /v1/auth/login or OAuth flow.text Copy
Authorization: Bearer <jwt_token>
API Key -- for server-to-server integration.text Copy
X-API-Key: <api_key>
Error Handling (RFC 7807 Problem Details)#
All errors use the RFC 7807 Problem Details format:
json Copy
{
"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
All list endpoints support:
Parameter
Default
Max
Description
page
1
--
Page number
limit
20
100
Items per page
Response envelope:
json Copy
{
"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.
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.
#
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):
Request ID -- Generates X-Request-ID for tracing
Request Context -- Async local storage for deep access
Performance Metrics -- P95 tracking (target: 100ms)
Problem Details Error Handler -- RFC 7807
Secure Headers -- CSP, HSTS, X-Frame-Options, etc.
CORS -- Origin whitelist with dev mode bypass
Logger -- Structured logging (non-production)
Compression -- gzip response compression
Timing -- Server-Timing header
Input Sanitization -- XSS, SQLi, command injection protection
Asset Metadata Sanitization -- Upload-specific protection
Rate Limiting -- Per-user/IP with Redis backing
API Versioning -- Path and header-based version resolution