Eve library

Yemaya API Reference

Guide

Revision 1

On this page

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

Base URL#

text
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',
});