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.
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 windowX-RateLimit-Remaining: Remaining requestsX-RateLimit-Reset: Unix timestamp when limit resets
Authentication (/api/v1/auth)#
Register User#
POST /auth/register
Create a new user account.
Request Body:
{
"email": "user@example.com",
"password": "SecureP@ss123",
"username": "johndoe",
"name": "John Doe"
}
Response: 201 Created
{
"user": { "id": "usr_...", "email": "...", "username": "..." },
"accessToken": "eyJ...",
"refreshToken": "..."
}
Login#
POST /auth/login
Authenticate with email and password.
Logout#
POST /auth/logout
Invalidate current session.
Refresh Token#
POST /auth/refresh
Get new access token using refresh token.
Email Verification#
POST /auth/email/verify
POST /auth/email/resend
Password Reset#
POST /auth/password/reset
POST /auth/password/reset/verify
POST /auth/password/reset/confirm
OAuth#
GET /auth/oauth/{provider}
GET /auth/oauth/{provider}/callback
Supported providers: google, github, discord
Sessions#
GET /auth/sessions
DELETE /auth/sessions/{id}
DELETE /auth/sessions
API Keys#
GET /auth/api-keys
POST /auth/api-keys
DELETE /auth/api-keys/{id}
AI Generation (/api/v1/ai)#
Text Generation#
POST /ai/text
POST /ai/text/sync
Generate text using LLM providers.
Request Body:
{
"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:
{
"id": "gen_...",
"text": "...",
"model": "claude-3-sonnet",
"usage": {
"promptTokens": 50,
"completionTokens": 450,
"totalTokens": 500
},
"cost": 0.0025
}
Image Generation#
POST /ai/images
POST /ai/images/sync
Generate images using AI models (DALL-E, Stable Diffusion).
Request Body:
{
"prompt": "A futuristic city at sunset, cyberpunk style",
"model": "dall-e-3",
"size": "1024x1024",
"quality": "hd",
"n": 1
}
Audio Generation#
POST /ai/audio
POST /ai/audio/sync
Generate audio (speech, music, sound effects).
3D Model Generation#
POST /ai/3d-models
Generate 3D models from text or images.
Code Generation#
POST /ai/code
POST /ai/code/sync
Generate code with AI assistance.
Embeddings#
POST /ai/embeddings
Generate vector embeddings for semantic search.
Job Management#
GET /ai/jobs
GET /ai/jobs/{jobId}
POST /ai/jobs/{jobId}/cancel
POST /ai/jobs/{jobId}/retry
Prompt Templates#
GET /ai/templates
POST /ai/templates
GET /ai/templates/{templateId}
PATCH /ai/templates/{templateId}
DELETE /ai/templates/{templateId}
POST /ai/templates/use
Usage & Providers#
GET /ai/usage
GET /ai/providers
GET /ai/models
3D Generation (/api/v1/3d)#
Text-to-3D#
POST /3d/generate/text
Generate 3D models from text descriptions.
Request Body:
{
"prompt": "A wooden treasure chest with gold trim",
"quality": "high",
"outputFormat": "glb",
"textureResolution": 2048,
"polyCount": "medium"
}
Image-to-3D#
POST /3d/generate/image
Generate 3D models from reference images.
Multi-view to 3D#
POST /3d/generate/multiview
Generate 3D models from multiple view images.
Batch Generation#
POST /3d/generate/batch/text
Generate multiple 3D models in a single request.
Job Management#
GET /3d/jobs
GET /3d/jobs/{jobId}
GET /3d/jobs/{jobId}/result
POST /3d/jobs/{jobId}/retry
DELETE /3d/jobs/{jobId}
Providers#
GET /3d/providers
GET /3d/providers/{provider}/models
GET /3d/providers/{provider}/status
Audio (/api/v1/audio)#
Music Generation#
POST /audio/music/generate
GET /audio/music/{generationId}/status
GET /audio/music
POST /audio/music/extend
POST /audio/music/remix
Voice Synthesis#
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#
POST /audio/sfx/generate
POST /audio/foley/generate
POST /audio/ambient/generate
Audio Processing#
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#
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#
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#
GET /assets
POST /assets
GET /assets/{id}
PATCH /assets/{id}
DELETE /assets/{id}
GET /assets/{id}/download
POST /assets/{id}/complete
Asset Locking#
POST /assets/{id}/lock
POST /assets/{id}/unlock
Asset Versions#
GET /assets/{id}/versions
POST /assets/{id}/versions
GET /assets/{id}/versions/{version}
POST /assets/{id}/versions/{version}/restore
Folders#
GET /assets/folders
POST /assets/folders
GET /assets/folders/{id}
PATCH /assets/folders/{id}
DELETE /assets/folders/{id}
POST /assets/folders/{id}/move
Operations#
POST /assets/{id}/move
POST /assets/bulk
GET /assets/search
Blender Integration (/api/v1/blender)#
Connection#
POST /blender/sessions/{sessionId}/connect
DELETE /blender/sessions/{sessionId}/connect
GET /blender/sessions/{sessionId}/status
Scene & Objects#
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#
POST /blender/sessions/{sessionId}/mesh/create
POST /blender/sessions/{sessionId}/mesh/import
POST /blender/sessions/{sessionId}/mesh/export
Modifiers & Materials#
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#
POST /blender/sessions/{sessionId}/rigging/auto-rig
POST /blender/sessions/{sessionId}/rigging/weight-paint
Rendering#
POST /blender/sessions/{sessionId}/render
GET /blender/sessions/{sessionId}/render/{jobId}
DELETE /blender/sessions/{sessionId}/render/{jobId}
Advanced Features#
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#
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#
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#
POST /gpu-jobs/webhooks
GET /gpu-jobs/webhooks
DELETE /gpu-jobs/webhooks/{id}
POST /gpu-jobs/webhooks/{id}/test
Health & Monitoring#
GET /gpu-jobs/health
GET /gpu-jobs/metrics
GET /gpu-jobs/stats
A/B Testing#
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#
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#
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#
POST /analytics/metrics/query
GET /analytics/metrics/available
Events#
POST /analytics/events
POST /analytics/events/batch
GET /analytics/events
Funnels#
GET /analytics/funnels
POST /analytics/funnels
GET /analytics/funnels/{funnelId}
DELETE /analytics/funnels/{funnelId}
POST /analytics/funnels/{funnelId}/analyze
Cohorts#
GET /analytics/cohorts
POST /analytics/cohorts
GET /analytics/cohorts/{cohortId}
DELETE /analytics/cohorts/{cohortId}
POST /analytics/cohorts/{cohortId}/analyze
Dashboards#
GET /analytics/dashboards
POST /analytics/dashboards
GET /analytics/dashboards/{dashboardId}
PATCH /analytics/dashboards/{dashboardId}
DELETE /analytics/dashboards/{dashboardId}
POST /analytics/dashboards/{dashboardId}/duplicate
Reports#
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#
POST /analytics/export
GET /analytics/export
GET /analytics/export/{jobId}
POST /analytics/export/{jobId}/cancel
Agent Management (/api/v1/agents)#
Agent Configuration#
GET /agents
POST /agents
GET /agents/{agentId}
PATCH /agents/{agentId}
DELETE /agents/{agentId}
Agent Commands#
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#
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#
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#
POST /agents/{agentId}/messages
GET /agents/{agentId}/messages
POST /agents/broadcast
Metrics#
GET /agents/{agentId}/metrics
GET /agents/pools/{poolId}/metrics
GET /agents/metrics
Admin (/api/v1/admin)#
Requires admin role
System#
GET /admin/system/status
GET /admin/system/metrics
Users#
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#
GET /admin/organizations
GET /admin/organizations/{orgId}
PATCH /admin/organizations/{orgId}
Moderation#
GET /admin/moderation/reports
GET /admin/moderation/reports/{reportId}
POST /admin/moderation/reports/{reportId}/resolve
GET /admin/moderation/logs
Feature Flags#
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#
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#
GET /admin/cache/stats
POST /admin/cache/invalidate
POST /admin/cache/flush
Database#
GET /admin/database/stats
GET /admin/database/migrations
Maintenance#
GET /admin/maintenance
PUT /admin/maintenance
Audit Logs#
GET /admin/audit-logs
Announcements#
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:
{
"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:
POST /webhooks
{
"url": "https://your-server.com/webhook",
"events": ["job.completed", "job.failed"],
"secret": "your-webhook-secret"
}
Webhook Signature Verification#
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#
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',
});