# Yemaya API Reference

Complete reference for all implemented API endpoints. The API uses OpenAPI 3.0
specification with Zod schema validation.

## Base URL

```
Production: https://api.yemaya.io/v1
Development: http://localhost:3000/api/v1
```

## Authentication

All endpoints require authentication via Bearer token unless marked as public.

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" https://api.yemaya.io/v1/...
```

## Rate Limiting

| Tier       | Requests/min | Burst |
| ---------- | ------------ | ----- |
| Free       | 60           | 10    |
| Pro        | 300          | 50    |
| Enterprise | 1000         | 200   |

Rate limit headers are included in all responses:

- `X-RateLimit-Limit`: Maximum requests per window
- `X-RateLimit-Remaining`: Remaining requests
- `X-RateLimit-Reset`: Unix timestamp when limit resets

---

## Authentication (`/api/v1/auth`)

### Register User

```http
POST /auth/register
```

Create a new user account.

**Request Body:**

```json
{
  "email": "user@example.com",
  "password": "SecureP@ss123",
  "username": "johndoe",
  "name": "John Doe"
}
```

**Response:** `201 Created`

```json
{
  "user": { "id": "usr_...", "email": "...", "username": "..." },
  "accessToken": "eyJ...",
  "refreshToken": "..."
}
```

### Login

```http
POST /auth/login
```

Authenticate with email and password.

### Logout

```http
POST /auth/logout
```

Invalidate current session.

### Refresh Token

```http
POST /auth/refresh
```

Get new access token using refresh token.

### Email Verification

```http
POST /auth/email/verify
POST /auth/email/resend
```

### Password Reset

```http
POST /auth/password/reset
POST /auth/password/reset/verify
POST /auth/password/reset/confirm
```

### OAuth

```http
GET /auth/oauth/{provider}
GET /auth/oauth/{provider}/callback
```

Supported providers: `google`, `github`, `discord`

### Sessions

```http
GET /auth/sessions
DELETE /auth/sessions/{id}
DELETE /auth/sessions
```

### API Keys

```http
GET /auth/api-keys
POST /auth/api-keys
DELETE /auth/api-keys/{id}
```

---

## AI Generation (`/api/v1/ai`)

### Text Generation

```http
POST /ai/text
POST /ai/text/sync
```

Generate text using LLM providers.

**Request Body:**

```json
{
  "prompt": "Write a character backstory for a medieval knight",
  "model": "claude-3-sonnet",
  "maxTokens": 1000,
  "temperature": 0.7,
  "systemPrompt": "You are a creative writing assistant."
}
```

**Response:**

```json
{
  "id": "gen_...",
  "text": "...",
  "model": "claude-3-sonnet",
  "usage": {
    "promptTokens": 50,
    "completionTokens": 450,
    "totalTokens": 500
  },
  "cost": 0.0025
}
```

### Image Generation

```http
POST /ai/images
POST /ai/images/sync
```

Generate images using AI models (DALL-E, Stable Diffusion).

**Request Body:**

```json
{
  "prompt": "A futuristic city at sunset, cyberpunk style",
  "model": "dall-e-3",
  "size": "1024x1024",
  "quality": "hd",
  "n": 1
}
```

### Audio Generation

```http
POST /ai/audio
POST /ai/audio/sync
```

Generate audio (speech, music, sound effects).

### 3D Model Generation

```http
POST /ai/3d-models
```

Generate 3D models from text or images.

### Code Generation

```http
POST /ai/code
POST /ai/code/sync
```

Generate code with AI assistance.

### Embeddings

```http
POST /ai/embeddings
```

Generate vector embeddings for semantic search.

### Job Management

```http
GET /ai/jobs
GET /ai/jobs/{jobId}
POST /ai/jobs/{jobId}/cancel
POST /ai/jobs/{jobId}/retry
```

### Prompt Templates

```http
GET /ai/templates
POST /ai/templates
GET /ai/templates/{templateId}
PATCH /ai/templates/{templateId}
DELETE /ai/templates/{templateId}
POST /ai/templates/use
```

### Usage & Providers

```http
GET /ai/usage
GET /ai/providers
GET /ai/models
```

---

## 3D Generation (`/api/v1/3d`)

### Text-to-3D

```http
POST /3d/generate/text
```

Generate 3D models from text descriptions.

**Request Body:**

```json
{
  "prompt": "A wooden treasure chest with gold trim",
  "quality": "high",
  "outputFormat": "glb",
  "textureResolution": 2048,
  "polyCount": "medium"
}
```

### Image-to-3D

```http
POST /3d/generate/image
```

Generate 3D models from reference images.

### Multi-view to 3D

```http
POST /3d/generate/multiview
```

Generate 3D models from multiple view images.

### Batch Generation

```http
POST /3d/generate/batch/text
```

Generate multiple 3D models in a single request.

### Job Management

```http
GET /3d/jobs
GET /3d/jobs/{jobId}
GET /3d/jobs/{jobId}/result
POST /3d/jobs/{jobId}/retry
DELETE /3d/jobs/{jobId}
```

### Providers

```http
GET /3d/providers
GET /3d/providers/{provider}/models
GET /3d/providers/{provider}/status
```

---

## Audio (`/api/v1/audio`)

### Music Generation

```http
POST /audio/music/generate
GET /audio/music/{generationId}/status
GET /audio/music
POST /audio/music/extend
POST /audio/music/remix
```

### Voice Synthesis

```http
GET /audio/voices
GET /audio/voices/{voiceId}
POST /audio/speech/synthesize
POST /audio/voices/clone
DELETE /audio/voices/{voiceId}
POST /audio/speech/batch
```

### Sound Design

```http
POST /audio/sfx/generate
POST /audio/foley/generate
POST /audio/ambient/generate
```

### Audio Processing

```http
POST /audio/process/normalize
POST /audio/process/denoise
POST /audio/process/stems
POST /audio/process/spatial
POST /audio/process/convert
POST /audio/process/analyze
```

### DAW Integration

```http
POST /audio/daw/connect
GET /audio/daw/status
POST /audio/daw/disconnect
POST /audio/daw/transport
GET /audio/daw/session
GET /audio/daw/tracks
POST /audio/daw/tracks
PATCH /audio/daw/tracks/{trackId}
DELETE /audio/daw/tracks/{trackId}
POST /audio/daw/export
```

### MIDI

```http
GET /audio/midi/devices
GET /audio/midi/mappings
POST /audio/midi/mappings
DELETE /audio/midi/mappings/{mappingId}
POST /audio/midi/send
```

---

## Assets (`/api/v1/assets`)

### Asset CRUD

```http
GET /assets
POST /assets
GET /assets/{id}
PATCH /assets/{id}
DELETE /assets/{id}
GET /assets/{id}/download
POST /assets/{id}/complete
```

### Asset Locking

```http
POST /assets/{id}/lock
POST /assets/{id}/unlock
```

### Asset Versions

```http
GET /assets/{id}/versions
POST /assets/{id}/versions
GET /assets/{id}/versions/{version}
POST /assets/{id}/versions/{version}/restore
```

### Folders

```http
GET /assets/folders
POST /assets/folders
GET /assets/folders/{id}
PATCH /assets/folders/{id}
DELETE /assets/folders/{id}
POST /assets/folders/{id}/move
```

### Operations

```http
POST /assets/{id}/move
POST /assets/bulk
GET /assets/search
```

---

## Blender Integration (`/api/v1/blender`)

### Connection

```http
POST /blender/sessions/{sessionId}/connect
DELETE /blender/sessions/{sessionId}/connect
GET /blender/sessions/{sessionId}/status
```

### Scene & Objects

```http
GET /blender/sessions/{sessionId}/scene
GET /blender/sessions/{sessionId}/objects
GET /blender/sessions/{sessionId}/objects/{objectId}
DELETE /blender/sessions/{sessionId}/objects/{objectId}
PUT /blender/sessions/{sessionId}/objects/{objectId}/transform
```

### Mesh Operations

```http
POST /blender/sessions/{sessionId}/mesh/create
POST /blender/sessions/{sessionId}/mesh/import
POST /blender/sessions/{sessionId}/mesh/export
```

### Modifiers & Materials

```http
POST /blender/sessions/{sessionId}/modifiers
POST /blender/sessions/{sessionId}/objects/{objectId}/modifiers/{modifierName}/apply
POST /blender/sessions/{sessionId}/materials
POST /blender/sessions/{sessionId}/objects/{objectId}/materials/{materialId}
```

### Rigging & Animation

```http
POST /blender/sessions/{sessionId}/rigging/auto-rig
POST /blender/sessions/{sessionId}/rigging/weight-paint
```

### Rendering

```http
POST /blender/sessions/{sessionId}/render
GET /blender/sessions/{sessionId}/render/{jobId}
DELETE /blender/sessions/{sessionId}/render/{jobId}
```

### Advanced Features

```http
POST /blender/sessions/{sessionId}/geometry-nodes
POST /blender/sessions/{sessionId}/hair
POST /blender/sessions/{sessionId}/cloth
POST /blender/sessions/{sessionId}/cloth/{objectId}/bake
POST /blender/sessions/{sessionId}/environment/hdri
POST /blender/sessions/{sessionId}/environment/terrain
```

### File Operations

```http
POST /blender/sessions/{sessionId}/file/open
POST /blender/sessions/{sessionId}/file/save
POST /blender/sessions/{sessionId}/file/new
```

---

## GPU Jobs (`/api/v1/gpu-jobs`)

### Job Management

```http
POST /gpu-jobs
GET /gpu-jobs
GET /gpu-jobs/{id}
DELETE /gpu-jobs/{id}
POST /gpu-jobs/{id}/retry
GET /gpu-jobs/{id}/logs
POST /gpu-jobs/estimate
```

### Webhooks

```http
POST /gpu-jobs/webhooks
GET /gpu-jobs/webhooks
DELETE /gpu-jobs/webhooks/{id}
POST /gpu-jobs/webhooks/{id}/test
```

### Health & Monitoring

```http
GET /gpu-jobs/health
GET /gpu-jobs/metrics
GET /gpu-jobs/stats
```

### A/B Testing

```http
POST /gpu-jobs/ab-tests
GET /gpu-jobs/ab-tests
GET /gpu-jobs/ab-tests/{testId}
POST /gpu-jobs/ab-tests/{testId}/stop
DELETE /gpu-jobs/ab-tests/{testId}
```

### Circuit Breakers

```http
GET /gpu-jobs/circuit-breakers
GET /gpu-jobs/circuit-breakers/{provider}
POST /gpu-jobs/circuit-breakers/{provider}/reset
PATCH /gpu-jobs/circuit-breakers/{provider}/config
```

### Dead Letter Queue

```http
GET /gpu-jobs/dlq
GET /gpu-jobs/dlq/stats
GET /gpu-jobs/dlq/{entryId}
POST /gpu-jobs/dlq/{entryId}/replay
POST /gpu-jobs/dlq/replay
DELETE /gpu-jobs/dlq/{entryId}
POST /gpu-jobs/dlq/purge
```

---

## Analytics (`/api/v1/analytics`)

### Metrics

```http
POST /analytics/metrics/query
GET /analytics/metrics/available
```

### Events

```http
POST /analytics/events
POST /analytics/events/batch
GET /analytics/events
```

### Funnels

```http
GET /analytics/funnels
POST /analytics/funnels
GET /analytics/funnels/{funnelId}
DELETE /analytics/funnels/{funnelId}
POST /analytics/funnels/{funnelId}/analyze
```

### Cohorts

```http
GET /analytics/cohorts
POST /analytics/cohorts
GET /analytics/cohorts/{cohortId}
DELETE /analytics/cohorts/{cohortId}
POST /analytics/cohorts/{cohortId}/analyze
```

### Dashboards

```http
GET /analytics/dashboards
POST /analytics/dashboards
GET /analytics/dashboards/{dashboardId}
PATCH /analytics/dashboards/{dashboardId}
DELETE /analytics/dashboards/{dashboardId}
POST /analytics/dashboards/{dashboardId}/duplicate
```

### Reports

```http
GET /analytics/reports
POST /analytics/reports
GET /analytics/reports/{reportId}
DELETE /analytics/reports/{reportId}
POST /analytics/reports/{reportId}/generate
GET /analytics/reports/scheduled
POST /analytics/reports/scheduled
GET /analytics/reports/scheduled/{scheduleId}
PATCH /analytics/reports/scheduled/{scheduleId}
DELETE /analytics/reports/scheduled/{scheduleId}
```

### Export

```http
POST /analytics/export
GET /analytics/export
GET /analytics/export/{jobId}
POST /analytics/export/{jobId}/cancel
```

---

## Agent Management (`/api/v1/agents`)

### Agent Configuration

```http
GET /agents
POST /agents
GET /agents/{agentId}
PATCH /agents/{agentId}
DELETE /agents/{agentId}
```

### Agent Commands

```http
POST /agents/{agentId}/command
POST /agents/{agentId}/start
POST /agents/{agentId}/stop
POST /agents/{agentId}/pause
POST /agents/{agentId}/resume
GET /agents/{agentId}/health
```

### Task Management

```http
GET /agents/tasks
POST /agents/tasks
GET /agents/tasks/{taskId}
POST /agents/tasks/{taskId}/cancel
POST /agents/tasks/{taskId}/retry
GET /agents/tasks/{taskId}/result
```

### Agent Pools

```http
GET /agents/pools
POST /agents/pools
GET /agents/pools/{poolId}
PATCH /agents/pools/{poolId}
DELETE /agents/pools/{poolId}
POST /agents/pools/{poolId}/agents/{agentId}
DELETE /agents/pools/{poolId}/agents/{agentId}
```

### Messaging

```http
POST /agents/{agentId}/messages
GET /agents/{agentId}/messages
POST /agents/broadcast
```

### Metrics

```http
GET /agents/{agentId}/metrics
GET /agents/pools/{poolId}/metrics
GET /agents/metrics
```

---

## Admin (`/api/v1/admin`)

_Requires admin role_

### System

```http
GET /admin/system/status
GET /admin/system/metrics
```

### Users

```http
GET /admin/users
POST /admin/users
GET /admin/users/{userId}
PATCH /admin/users/{userId}
DELETE /admin/users/{userId}
POST /admin/users/bulk
POST /admin/users/{userId}/impersonate
```

### Organizations

```http
GET /admin/organizations
GET /admin/organizations/{orgId}
PATCH /admin/organizations/{orgId}
```

### Moderation

```http
GET /admin/moderation/reports
GET /admin/moderation/reports/{reportId}
POST /admin/moderation/reports/{reportId}/resolve
GET /admin/moderation/logs
```

### Feature Flags

```http
GET /admin/feature-flags
POST /admin/feature-flags
GET /admin/feature-flags/{flagId}
PATCH /admin/feature-flags/{flagId}
DELETE /admin/feature-flags/{flagId}
```

### Background Jobs

```http
GET /admin/jobs
GET /admin/jobs/{jobId}
POST /admin/jobs/{jobId}/retry
POST /admin/jobs/{jobId}/cancel
GET /admin/jobs/queues/stats
POST /admin/jobs/queues/{queueName}/pause
POST /admin/jobs/queues/{queueName}/resume
```

### Cache

```http
GET /admin/cache/stats
POST /admin/cache/invalidate
POST /admin/cache/flush
```

### Database

```http
GET /admin/database/stats
GET /admin/database/migrations
```

### Maintenance

```http
GET /admin/maintenance
PUT /admin/maintenance
```

### Audit Logs

```http
GET /admin/audit-logs
```

### Announcements

```http
GET /admin/announcements
POST /admin/announcements
GET /admin/announcements/{announcementId}
PATCH /admin/announcements/{announcementId}
DELETE /admin/announcements/{announcementId}
```

---

## Error Responses

All errors follow this format:

```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ],
    "requestId": "req_abc123"
  }
}
```

### Common Error Codes

| Code                  | HTTP Status | Description                       |
| --------------------- | ----------- | --------------------------------- |
| `UNAUTHORIZED`        | 401         | Missing or invalid authentication |
| `FORBIDDEN`           | 403         | Insufficient permissions          |
| `NOT_FOUND`           | 404         | Resource not found                |
| `VALIDATION_ERROR`    | 400         | Invalid request parameters        |
| `RATE_LIMITED`        | 429         | Too many requests                 |
| `INTERNAL_ERROR`      | 500         | Server error                      |
| `SERVICE_UNAVAILABLE` | 503         | Service temporarily unavailable   |

---

## Webhooks

Register webhooks to receive real-time notifications:

```http
POST /webhooks
{
  "url": "https://your-server.com/webhook",
  "events": ["job.completed", "job.failed"],
  "secret": "your-webhook-secret"
}
```

### Webhook Signature Verification

```javascript
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  return signature === `sha256=${expected}`;
}
```

---

## SDKs

Official SDKs are available for easy integration:

- **TypeScript/JavaScript**: `@yemaya/sdk`
- **Python**: `yemaya-sdk` (coming soon)
- **C++**: `yemaya-cpp` (coming soon)

### TypeScript SDK Example

```typescript
import { YemayaClient } from '@yemaya/sdk';

const client = new YemayaClient({
  apiKey: 'your-api-key',
  baseUrl: 'https://api.yemaya.io/v1',
});

// Generate text
const result = await client.ai.generateText({
  prompt: 'Write a story opening',
  model: 'claude-3-sonnet',
});

// Generate 3D model
const model = await client.threeD.generate({
  prompt: 'A wooden chair',
  quality: 'high',
});
```

---

## Related Documentation

- [Getting Started](../getting-started/README.md)
- [SDK Tutorials](./sdk-tutorials.md)
- [Webhooks Guide](./webhooks.md)
- [Rate Limits](./rate-limits.md)
- [Examples](./examples.md)
