# Aja Domain API Reference

Aja is the motion capture and animation domain of the Oshun platform. It
provides two backend services for processing video into motion data, retargeting
motion between skeletons, and orchestrating multi-stage pipeline jobs.

| Service               | Framework | Default Port | Purpose                                          |
| --------------------- | --------- | ------------ | ------------------------------------------------ |
| `svc-motion-pipeline` | Fastify   | 8090         | Pipeline orchestration, job management, delivery |
| `svc-motion-ai`       | Hono      | 3040         | AI-powered motion processing (V2M, retargeting)  |

There is also a companion CLI tool (`apps/aja/cli`) and a reference video
service (`apps/aja/svc-reference-video`) for video library management.

---

## Common Patterns

### Authentication

Both services accept tenant and user identity via headers:

```
X-Tenant-ID: tenant_abc
X-User-ID: usr_123
```

The motion pipeline service uses these to scope job visibility and ownership.

### Error Format

Both services return errors with `code` and `message` fields:

```json
{
  "code": "JOB_NOT_FOUND",
  "message": "Job not found"
}
```

---

## 1. Motion Pipeline Service (`svc-motion-pipeline`)

Base URL: `/v1/pipeline`

Source: `apps/aja/svc-motion-pipeline/src/app.ts`

The motion pipeline service orchestrates multi-stage motion processing jobs.
Each job progresses through configurable pipeline stages (video preprocessing,
pose estimation, temporal smoothing, format conversion, quality analysis, etc.)
and supports real-time progress streaming via SSE, webhook callbacks, and
polling.

### 1.1 Health & Statistics

| Method | Path                 | Description                                           |
| ------ | -------------------- | ----------------------------------------------------- |
| GET    | `/health`            | Service health with component status                  |
| GET    | `/v1/pipeline/stats` | Queue statistics (waiting, active, completed, failed) |

#### Health Response

```json
{
  "status": "healthy",
  "components": {
    "jobManager": {
      "name": "Job Manager",
      "status": "healthy",
      "lastCheck": "..."
    },
    "webhookService": {
      "name": "Webhook Service",
      "status": "healthy",
      "lastCheck": "..."
    },
    "configRepository": {
      "name": "Configuration Repository",
      "status": "healthy",
      "lastCheck": "..."
    }
  },
  "uptimeSeconds": 86400,
  "lastCheck": "2026-02-14T12:00:00.000Z"
}
```

### 1.2 Pipeline Configuration

Configurations define the stages, quality presets, timeouts, and output format
for a pipeline run.

| Method | Path                                  | Description                  |
| ------ | ------------------------------------- | ---------------------------- |
| GET    | `/v1/pipeline/configs`                | List configurations          |
| GET    | `/v1/pipeline/configs/:configId`      | Get configuration by ID      |
| GET    | `/v1/pipeline/configs/by-name/:name`  | Get configuration by name    |
| POST   | `/v1/pipeline/configs`                | Create from JSON             |
| POST   | `/v1/pipeline/configs/yaml`           | Create from YAML definition  |
| GET    | `/v1/pipeline/configs/:configId/yaml` | Export configuration as YAML |
| DELETE | `/v1/pipeline/configs/:configId`      | Delete a configuration       |
| GET    | `/v1/pipeline/presets`                | List all quality presets     |

#### List Configs Query Parameters

| Parameter       | Type   | Description                  |
| --------------- | ------ | ---------------------------- |
| `domain`        | string | Filter by domain (see below) |
| `qualityPreset` | string | Filter by quality preset     |

#### Pipeline Domains

| Domain         | Description                       |
| -------------- | --------------------------------- |
| `yoga`         | Yoga pose and flow sequences      |
| `fitness`      | General fitness and exercise      |
| `dance`        | Dance choreography                |
| `martial-arts` | Martial arts forms and techniques |
| `general`      | General-purpose motion capture    |

#### Quality Presets

| Preset     | Description                                         |
| ---------- | --------------------------------------------------- |
| `draft`    | Fast processing, lower accuracy, for previews       |
| `standard` | Balanced speed and quality for production use       |
| `high`     | High accuracy with advanced filtering               |
| `ultra`    | Maximum quality with all enhancement stages enabled |

Each preset affects the number and configuration of pipeline stages (e.g.,
whether physics refinement, super-resolution, and style transfer stages are
enabled).

#### Create Configuration Request

```json
{
  "name": "yoga-high",
  "description": "High-quality yoga motion capture pipeline",
  "domain": "yoga",
  "qualityPreset": "high",
  "globalTimeoutMs": 3600000,
  "failFast": false,
  "metadata": {
    "team": "motion-team"
  }
}
```

#### Create Configuration from YAML

```json
{
  "yaml": "name: custom-pipeline\ndomain: general\nqualityPreset: standard\nstages:\n  - name: preprocessing\n    enabled: true\n    timeoutMs: 60000\n  - name: pose-estimation\n    enabled: true\n    timeoutMs: 300000\n"
}
```

### 1.3 Job Management

Jobs are the primary work unit. A job runs a pipeline configuration against
input data and produces motion data outputs.

| Method | Path                                | Description                       |
| ------ | ----------------------------------- | --------------------------------- |
| POST   | `/v1/pipeline/jobs`                 | Submit a new job                  |
| GET    | `/v1/pipeline/jobs`                 | List jobs (scoped to tenant)      |
| GET    | `/v1/pipeline/jobs/:jobId`          | Get job status (polling endpoint) |
| POST   | `/v1/pipeline/jobs/:jobId/cancel`   | Cancel a job                      |
| POST   | `/v1/pipeline/jobs/:jobId/retry`    | Retry a failed job                |
| PATCH  | `/v1/pipeline/jobs/:jobId/priority` | Update job priority               |
| POST   | `/v1/pipeline/jobs/batch`           | Batch operations on multiple jobs |

#### Submit Job Request

```json
{
  "pipelineConfig": "yoga-high",
  "input": {
    "videoUrl": "https://storage.example.com/videos/session-001.mp4",
    "frameRate": 30,
    "startTimeSec": 0,
    "endTimeSec": 120
  },
  "options": {
    "priority": "normal",
    "callbackUrl": "https://hooks.example.com/motion-complete",
    "metadata": {
      "sessionId": "sess_001",
      "instructorId": "inst_042"
    }
  },
  "webhook": {
    "url": "https://hooks.example.com/motion-events",
    "secret": "whsec_...",
    "events": [
      "job.queued",
      "job.started",
      "job.progress",
      "job.completed",
      "job.failed"
    ]
  }
}
```

The `pipelineConfig` field accepts either a configuration ID, a configuration
name (string), or an inline configuration object.

#### Submit Job Response (202 Accepted)

```json
{
  "jobId": "job_abc123",
  "status": "pending",
  "createdAt": "2026-02-14T12:00:00.000Z",
  "pollUrl": "/v1/pipeline/jobs/job_abc123",
  "streamUrl": "/v1/pipeline/jobs/job_abc123/stream"
}
```

#### Job List Query Parameters

| Parameter | Type   | Description                   |
| --------- | ------ | ----------------------------- |
| `status`  | string | Comma-separated status filter |
| `limit`   | number | Max results                   |
| `offset`  | number | Skip count                    |

#### Update Priority Request

```json
{ "priority": "high" }
```

Priority values: `critical`, `high`, `normal`, `low`, `background`

#### Cancel Job Request

```json
{ "reason": "User cancelled from UI" }
```

#### Batch Operations Request

```json
{
  "operation": "cancel",
  "jobIds": ["job_001", "job_002", "job_003"],
  "reason": "Batch cancellation"
}
```

### 1.4 Job Outputs & Downloads

| Method | Path                                | Description                    |
| ------ | ----------------------------------- | ------------------------------ |
| GET    | `/v1/pipeline/jobs/:jobId/outputs`  | List available output files    |
| POST   | `/v1/pipeline/jobs/:jobId/download` | Generate a signed download URL |

Output listing is only available for completed jobs. Each output includes
format, file size, and checksum information.

#### Download Request

```json
{
  "outputIndex": 0,
  "format": "fbx",
  "expiresInSec": 3600
}
```

#### Download Response

```json
{
  "url": "https://storage.example.com/outputs/job_abc/output.fbx?...",
  "expiresAt": "2026-02-14T13:00:00.000Z",
  "sizeBytes": 1048576,
  "checksum": "sha256:abc123..."
}
```

### 1.5 SSE Progress Streaming

| Method | Path                              | Description             |
| ------ | --------------------------------- | ----------------------- |
| GET    | `/v1/pipeline/jobs/:jobId/stream` | SSE progress stream     |
| GET    | `/v1/pipeline/streams/stats`      | Active connection count |

The SSE endpoint opens a persistent connection and streams events as the job
progresses. Only active jobs (pending, queued, running) can be streamed.

#### SSE Event Types

| Event Type     | Description                               |
| -------------- | ----------------------------------------- |
| `connected`    | Initial connection with job status        |
| `progress`     | Overall progress update                   |
| `stage_update` | Individual stage started/completed/failed |
| `completion`   | Job completed with results and stats      |
| `error`        | Job failed with error details             |

#### SSE Progress Event Example

```
data: {"type":"progress","jobId":"job_abc","percentage":45,"currentStage":"pose-estimation","stagePercentage":72,"message":"Processing pose-estimation..."}
```

### 1.6 Webhook Management

| Method | Path                                      | Description                     |
| ------ | ----------------------------------------- | ------------------------------- |
| GET    | `/v1/pipeline/jobs/:jobId/webhooks`       | List webhook deliveries for job |
| GET    | `/v1/pipeline/webhooks/:deliveryId`       | Get delivery status             |
| POST   | `/v1/pipeline/webhooks/:deliveryId/retry` | Retry a failed delivery         |
| GET    | `/v1/pipeline/webhooks/stats`             | Webhook delivery statistics     |

#### Webhook Event Types

| Event             | Trigger                                 |
| ----------------- | --------------------------------------- |
| `job.queued`      | Job enters the queue                    |
| `job.started`     | Processing begins                       |
| `job.progress`    | At 25%, 50%, 75% completion (throttled) |
| `job.completed`   | Job finished successfully               |
| `job.failed`      | Job failed with error                   |
| `job.cancelled`   | Job was cancelled                       |
| `stage.started`   | Pipeline stage begins                   |
| `stage.completed` | Pipeline stage finishes                 |
| `stage.failed`    | Pipeline stage fails                    |

#### Webhook Payload Structure

```json
{
  "event": "job.completed",
  "jobId": "job_abc123",
  "timestamp": "2026-02-14T12:05:00.000Z",
  "data": {
    "result": {
      "primaryOutput": {
        "format": "fbx",
        "path": "/outputs/job_abc/output.fbx",
        "sizeBytes": 1048576,
        "checksum": "sha256:..."
      }
    },
    "stats": {
      "totalDurationMs": 45000,
      "stagesCompleted": 6,
      "stagesFailed": 0
    }
  }
}
```

---

## 2. Motion AI Service (`svc-motion-ai`)

Base URL: `/api/v1`

Default Port: 3040

Source: `apps/aja/svc-motion-ai/src/app.ts`

The motion AI service provides stateless AI-powered motion processing endpoints.
Each endpoint processes a request synchronously and returns results. For long
operations, the pipeline service wraps these calls as pipeline stages.

### 2.1 Health

| Method | Path      | Description  |
| ------ | --------- | ------------ |
| GET    | `/health` | Health check |

### 2.2 Video-to-Motion

Extracts motion data from video input by running video preprocessing, pose
estimation, keypoint normalization, and temporal processing.

| Method | Path                              | Description             |
| ------ | --------------------------------- | ----------------------- |
| POST   | `/api/v1/video-to-motion/process` | Process video to motion |

#### Request Body

```json
{
  "videoUrl": "https://storage.example.com/videos/session.mp4",
  "options": {
    "frameRate": 30,
    "startTime": 0,
    "endTime": 60,
    "poseModel": "mediapipe-holistic",
    "outputFormat": "bvh",
    "smoothing": {
      "enabled": true,
      "windowSize": 5,
      "method": "savitzky-golay"
    }
  }
}
```

#### Response

Returns extracted motion data with joint positions, rotations, and quality
metrics.

### 2.3 Motion Retargeting

Transfers motion from one skeleton topology to another, adjusting for bone
length differences and joint mapping.

| Method | Path                           | Description                       |
| ------ | ------------------------------ | --------------------------------- |
| POST   | `/api/v1/retargeting/retarget` | Retarget motion between skeletons |

#### Request Body

```json
{
  "sourceMotion": { "format": "bvh", "data": "..." },
  "sourceSkeleton": { "type": "mixamo", "jointCount": 65 },
  "targetSkeleton": { "type": "unreal-mannequin", "jointCount": 67 },
  "options": {
    "preserveFootContact": true,
    "adjustHipHeight": true,
    "ikEnabled": true
  }
}
```

### 2.4 Skeletal Animation

Generates or processes skeletal animation data for a target skeleton definition.

| Method | Path                       | Description        |
| ------ | -------------------------- | ------------------ |
| POST   | `/api/v1/skeletal/animate` | Animate a skeleton |

#### Request Body

```json
{
  "skeleton": {
    "type": "custom",
    "joints": [...],
    "hierarchy": [...]
  },
  "animation": {
    "type": "procedural",
    "params": {
      "style": "walk",
      "speed": 1.2,
      "direction": [0, 0, 1]
    }
  },
  "outputFormat": "fbx"
}
```

### 2.5 Video Analysis

Analyzes video content for motion quality, scene detection, and movement
classification without full motion extraction.

| Method | Path                       | Description                   |
| ------ | -------------------------- | ----------------------------- |
| POST   | `/api/v1/analysis/analyze` | Analyze video for motion data |

#### Request Body

```json
{
  "videoUrl": "https://storage.example.com/videos/reference.mp4",
  "analysisTypes": [
    "motion-quality",
    "scene-detection",
    "movement-classification"
  ],
  "options": {
    "sampleRate": 10,
    "confidenceThreshold": 0.8
  }
}
```

---

## Additional Services

### Reference Video Service (`svc-reference-video`)

Source: `apps/aja/svc-reference-video/src/`

A library management service for reference videos used in motion capture
workflows. Provides:

- **Video Ingestion** -- Upload and store reference videos
- **Metadata Extraction** -- Auto-extract duration, resolution, codec
- **Scene Detection** -- Identify scene boundaries
- **Video Categorization** -- Classify by movement type, domain
- **Video Search** -- Full-text and metadata search
- **Annotation** -- Timestamp-based annotations
- **Collaboration** -- Shared video collections and comments

### CLI Tool (`cli`)

Source: `apps/aja/cli/src/`

A command-line interface for interacting with the Aja services:

| Command   | Description                          |
| --------- | ------------------------------------ |
| `process` | Submit a video for motion processing |
| `jobs`    | List and manage pipeline jobs        |
| `config`  | Manage pipeline configurations       |
| `convert` | Convert between motion data formats  |
| `inspect` | Inspect motion data files            |
| `health`  | Check service health                 |
| `debug`   | Debug utilities                      |
