# Yemaya Domain API Reference

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.
   ```
   Authorization: Bearer <jwt_token>
   ```
2. **API Key** -- for server-to-server integration.
   ```
   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
