Complete reference documentation for the Yemaya REST API.
Overview#
The Yemaya API provides programmatic access to the creative production platform, enabling management of projects, assets, teams, and workflows.
Base URLs:
- Production:
https://api.yemaya.io/v1 - Staging:
https://api.staging.yemaya.io/v1 - Local Development:
http://localhost:3000/v1
OpenAPI Specification: Available at /openapi.json
Interactive Documentation:
- Swagger UI:
/docs - Scalar Reference:
/reference
Authentication#
Bearer Token (JWT)#
Most API endpoints require authentication via JWT bearer tokens. Include the
token in the Authorization header:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Token Lifecycle:
- Access tokens expire after 15 minutes
- Refresh tokens are valid for 7 days
- Use
POST /auth/refreshto obtain new access tokens
API Keys#
For server-to-server communication, use API keys:
X-API-Key: yek_live_abc123def456...
API keys can be created with specific scopes to limit permissions.
Rate Limiting#
| Authentication | Limit |
|---|---|
| Authenticated | 1000 requests/minute |
| Unauthenticated | 60 requests/minute |
Rate limit headers are included in all responses:
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1702345678
Response Format#
Success Response#
{
"success": true,
"data": { ... }
}
Paginated Response#
{
"data": [ ... ],
"meta": {
"page": 1,
"limit": 20,
"total": 150,
"totalPages": 8,
"hasMore": true
}
}
Error Response#
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid request data",
"details": {
"email": ["Invalid email format"]
}
}
}
HTTP Status Codes#
| Code | Description |
|---|---|
200 |
Success |
201 |
Created |
400 |
Bad Request - Invalid input |
401 |
Unauthorized - Missing or invalid token |
403 |
Forbidden - Insufficient permissions |
404 |
Not Found |
409 |
Conflict - Resource already exists |
429 |
Too Many Requests - Rate limited |
500 |
Internal Server Error |
Authentication Endpoints#
Register User#
Create a new user account.
POST /auth/register
Content-Type: application/json
{
"email": "user@example.com",
"password": "securePassword123!",
"name": "John Doe",
"acceptedTerms": true
}
Response (201 Created):
{
"success": true,
"data": {
"user": {
"id": "usr_abc123",
"email": "user@example.com",
"name": "John Doe",
"emailVerified": false,
"createdAt": "2024-01-15T10:30:00Z"
},
"tokens": {
"accessToken": "eyJhbG...",
"refreshToken": "ref_abc123...",
"expiresIn": 900
}
}
}
Login#
Authenticate with email and password.
POST /auth/login
Content-Type: application/json
{
"email": "user@example.com",
"password": "securePassword123!"
}
Response (200 OK):
{
"success": true,
"data": {
"user": {
"id": "usr_abc123",
"email": "user@example.com",
"name": "John Doe"
},
"tokens": {
"accessToken": "eyJhbG...",
"refreshToken": "ref_abc123...",
"expiresIn": 900
}
}
}
Refresh Token#
Get a new access token using a refresh token.
POST /auth/refresh
Content-Type: application/json
{
"refreshToken": "ref_abc123..."
}
Logout#
Invalidate current session.
POST /auth/logout
Authorization: Bearer <token>
OAuth Login#
Initiate OAuth flow with a provider.
GET /auth/oauth/{provider}?redirect=https://app.yemaya.io/callback
Supported Providers: google, github, discord, apple
OAuth callbacks are handled at:
GET /auth/oauth/{provider}/callback
On success, the API redirects to the redirect URL with tokens encoded in the
URL fragment.
Password Reset#
Request a password reset email.
POST /auth/password/reset
Content-Type: application/json
{
"email": "user@example.com"
}
Confirm Password Reset#
Set a new password using reset token.
POST /auth/password/reset/confirm
Content-Type: application/json
{
"token": "rst_abc123...",
"password": "newSecurePassword123!"
}
Verify Email#
Verify email address with token.
POST /auth/email/verify
Content-Type: application/json
{
"token": "ver_abc123..."
}
Session Management#
List Sessions#
Get all active sessions for the current user.
GET /auth/sessions
Authorization: Bearer <token>
Response:
{
"success": true,
"data": [
{
"id": "sess_abc123",
"device": "Chrome on macOS",
"ip": "192.168.1.1",
"location": "San Francisco, CA",
"lastActive": "2024-01-15T10:30:00Z",
"current": true
}
]
}
Revoke Session#
Revoke a specific session (logout from device).
DELETE /auth/sessions/{sessionId}
Authorization: Bearer <token>
Revoke All Sessions#
Logout from all devices except current.
DELETE /auth/sessions
Authorization: Bearer <token>
API Key Management#
List API Keys#
Get all API keys for the current user.
GET /auth/api-keys
Authorization: Bearer <token>
Create API Key#
Create a new API key with specific scopes.
POST /auth/api-keys
Authorization: Bearer <token>
Content-Type: application/json
{
"name": "CI/CD Pipeline",
"scopes": ["projects:read", "assets:read", "assets:write"],
"expiresAt": "2025-01-15T00:00:00Z"
}
Response (201 Created):
{
"success": true,
"data": {
"id": "key_abc123",
"name": "CI/CD Pipeline",
"key": "yek_live_abc123def456...",
"scopes": ["projects:read", "assets:read", "assets:write"],
"expiresAt": "2025-01-15T00:00:00Z"
},
"message": "Store this key securely - it won't be shown again"
}
Available Scopes:
| Scope | Description |
|---|---|
projects:read |
Read project data |
projects:write |
Create/update projects |
projects:delete |
Delete projects |
assets:read |
Read asset data |
assets:write |
Upload/update assets |
assets:delete |
Delete assets |
users:read |
Read user profiles |
organizations:read |
Read organization data |
organizations:write |
Manage organizations |
Delete API Key#
Revoke and delete an API key.
DELETE /auth/api-keys/{keyId}
Authorization: Bearer <token>
Projects#
List Projects#
Get paginated list of projects accessible to the current user.
GET /projects?page=1&limit=20&status=active&type=game
Authorization: Bearer <token>
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
page |
number | Page number (default: 1) |
limit |
number | Items per page (default: 20, max: 100) |
status |
string | Filter by status: draft, active, archived, completed |
type |
string | Filter by type: film, game, animation, mixed |
visibility |
string | Filter by visibility: private, team, public |
organizationId |
uuid | Filter by organization |
search |
string | Search in name and description |
owned |
boolean | Filter to owned projects only |
Response:
{
"data": [
{
"id": "proj_abc123",
"name": "Space Adventure",
"description": "A sci-fi game project",
"type": "game",
"status": "active",
"visibility": "team",
"thumbnailUrl": "https://cdn.yemaya.io/...",
"owner": {
"id": "usr_abc123",
"name": "John Doe"
},
"organization": {
"id": "org_abc123",
"name": "Game Studio Inc"
},
"memberCount": 5,
"assetCount": 150,
"createdAt": "2024-01-10T08:00:00Z",
"updatedAt": "2024-01-15T10:30:00Z"
}
],
"meta": {
"page": 1,
"limit": 20,
"total": 45,
"totalPages": 3,
"hasMore": true
}
}
Create Project#
Create a new project.
POST /projects
Authorization: Bearer <token>
Content-Type: application/json
{
"name": "My New Project",
"description": "An exciting new game",
"type": "game",
"visibility": "team",
"organizationId": "org_abc123",
"settings": {
"targetPlatforms": ["pc", "console"],
"gameEngine": "godot"
},
"tags": ["rpg", "indie"]
}
Project Types:
| Type | Description |
|---|---|
film |
Film/movie project |
game |
Video game project |
animation |
Animation project |
mixed |
Mixed media project |
Get Project#
Get project details by ID.
GET /projects/{projectId}
Authorization: Bearer <token>
Update Project#
Update project details.
PATCH /projects/{projectId}
Authorization: Bearer <token>
Content-Type: application/json
{
"name": "Updated Project Name",
"description": "Updated description",
"status": "completed"
}
Delete Project#
Permanently delete a project and all its contents.
DELETE /projects/{projectId}
Authorization: Bearer <token>
Archive Project#
Archive a project (can be restored later).
POST /projects/{projectId}/archive
Authorization: Bearer <token>
Restore Project#
Restore an archived project.
POST /projects/{projectId}/restore
Authorization: Bearer <token>
Duplicate Project#
Create a copy of a project.
POST /projects/{projectId}/duplicate
Authorization: Bearer <token>
Content-Type: application/json
{
"name": "My Project (Copy)",
"includeAssets": true
}
Upload Thumbnail#
Upload a thumbnail image for the project.
POST /projects/{projectId}/thumbnail
Authorization: Bearer <token>
Content-Type: multipart/form-data
file: <binary>
Project Members#
List Members#
Get all members of a project.
GET /projects/{projectId}/members
Authorization: Bearer <token>
Response:
{
"data": [
{
"userId": "usr_abc123",
"user": {
"id": "usr_abc123",
"name": "John Doe",
"email": "john@example.com",
"avatarUrl": "https://..."
},
"role": "owner",
"joinedAt": "2024-01-10T08:00:00Z"
}
],
"meta": { ... }
}
Roles:
| Role | Permissions |
|---|---|
owner |
Full access, can delete project |
admin |
Manage members, edit settings |
editor |
Create/edit content |
viewer |
Read-only access |
Add Member#
Invite a user to the project.
POST /projects/{projectId}/members
Authorization: Bearer <token>
Content-Type: application/json
{
"userId": "usr_def456",
"role": "editor"
}
Or invite by email:
{
"email": "newuser@example.com",
"role": "editor"
}
Update Member Role#
Update a member's role in the project.
PATCH /projects/{projectId}/members/{userId}
Authorization: Bearer <token>
Content-Type: application/json
{
"role": "admin"
}
Remove Member#
Remove a member from the project.
DELETE /projects/{projectId}/members/{userId}
Authorization: Bearer <token>
Leave Project#
Leave a project (cannot leave if you are the only owner).
POST /projects/{projectId}/leave
Authorization: Bearer <token>
Project Comments#
List Comments#
Get comments for a project.
GET /projects/{projectId}/comments?resourceType=asset&resourceId=ast_123
Authorization: Bearer <token>
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
resourceType |
string | Filter by resource type (e.g., asset, scene) |
resourceId |
uuid | Filter by resource ID |
resolved |
boolean | Filter by resolved status |
Create Comment#
Add a comment to the project.
POST /projects/{projectId}/comments
Authorization: Bearer <token>
Content-Type: application/json
{
"content": "This looks great! Can we adjust the lighting?",
"resourceType": "asset",
"resourceId": "ast_abc123",
"position": {
"x": 150,
"y": 200
},
"parentId": null
}
Update Comment#
Update a comment.
PATCH /projects/{projectId}/comments/{commentId}
Authorization: Bearer <token>
Content-Type: application/json
{
"content": "Updated comment text"
}
Delete Comment#
Delete a comment.
DELETE /projects/{projectId}/comments/{commentId}
Authorization: Bearer <token>
Resolve Comment#
Mark a comment as resolved.
POST /projects/{projectId}/comments/{commentId}/resolve
Authorization: Bearer <token>
Project Activity#
Get Activity#
Get activity log for a project.
GET /projects/{projectId}/activity?page=1&limit=50
Authorization: Bearer <token>
Response:
{
"data": [
{
"id": "act_abc123",
"type": "asset.uploaded",
"actor": {
"id": "usr_abc123",
"name": "John Doe"
},
"target": {
"type": "asset",
"id": "ast_abc123",
"name": "hero_model.fbx"
},
"metadata": {
"fileSize": 15000000,
"format": "fbx"
},
"timestamp": "2024-01-15T10:30:00Z"
}
],
"meta": { ... }
}
Assets#
Assets are managed within the context of a project.
List Assets#
Get assets in a project.
GET /projects/{projectId}/assets?type=model&folder=characters
Authorization: Bearer <token>
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
type |
string | Filter by type: model, texture, audio, video, script, document |
folder |
string | Filter by folder path |
search |
string | Search in name and tags |
tags |
string[] | Filter by tags |
Upload Asset#
Request a presigned URL for direct upload.
POST /projects/{projectId}/assets/upload
Authorization: Bearer <token>
Content-Type: application/json
{
"filename": "hero_model.fbx",
"contentType": "application/octet-stream",
"size": 15000000,
"folder": "characters"
}
Response:
{
"success": true,
"data": {
"uploadId": "upl_abc123",
"uploadUrl": "https://storage.yemaya.io/...",
"fields": { ... },
"expiresAt": "2024-01-15T11:00:00Z"
}
}
Then upload directly to the presigned URL:
PUT {uploadUrl}
Content-Type: application/octet-stream
<binary file data>
Confirm Upload#
Confirm that upload is complete.
POST /projects/{projectId}/assets/{uploadId}/confirm
Authorization: Bearer <token>
Content-Type: application/json
{
"name": "Hero Character Model",
"description": "Main character 3D model",
"tags": ["character", "hero", "3d"]
}
Get Asset#
Get asset details.
GET /projects/{projectId}/assets/{assetId}
Authorization: Bearer <token>
Update Asset#
Update asset metadata.
PATCH /projects/{projectId}/assets/{assetId}
Authorization: Bearer <token>
Content-Type: application/json
{
"name": "Updated Name",
"description": "Updated description",
"tags": ["updated", "tags"]
}
Delete Asset#
Delete an asset.
DELETE /projects/{projectId}/assets/{assetId}
Authorization: Bearer <token>
Move Asset#
Move asset to a different folder.
POST /projects/{projectId}/assets/{assetId}/move
Authorization: Bearer <token>
Content-Type: application/json
{
"folder": "characters/npcs"
}
Get Download URL#
Get a signed download URL.
GET /projects/{projectId}/assets/{assetId}/download
Authorization: Bearer <token>
Response:
{
"success": true,
"data": {
"url": "https://cdn.yemaya.io/...",
"expiresAt": "2024-01-15T11:00:00Z"
}
}
Asset Versions#
List Versions#
Get version history for an asset.
GET /projects/{projectId}/assets/{assetId}/versions
Authorization: Bearer <token>
Create Version#
Upload a new version of an asset.
POST /projects/{projectId}/assets/{assetId}/versions
Authorization: Bearer <token>
Content-Type: application/json
{
"filename": "hero_model_v2.fbx",
"contentType": "application/octet-stream",
"size": 16000000,
"changelog": "Added facial animations"
}
Restore Version#
Restore a previous version as the current version.
POST /projects/{projectId}/assets/{assetId}/versions/{versionId}/restore
Authorization: Bearer <token>
Asset Folders#
List Folders#
Get folder structure for a project.
GET /projects/{projectId}/folders
Authorization: Bearer <token>
Create Folder#
Create a new folder.
POST /projects/{projectId}/folders
Authorization: Bearer <token>
Content-Type: application/json
{
"name": "characters",
"parent": null
}
Rename Folder#
Rename a folder.
PATCH /projects/{projectId}/folders/{folderId}
Authorization: Bearer <token>
Content-Type: application/json
{
"name": "new_name"
}
Delete Folder#
Delete a folder and optionally its contents.
DELETE /projects/{projectId}/folders/{folderId}?deleteContents=false
Authorization: Bearer <token>
Organizations#
List Organizations#
Get organizations the current user is a member of.
GET /organizations
Authorization: Bearer <token>
Create Organization#
Create a new organization.
POST /organizations
Authorization: Bearer <token>
Content-Type: application/json
{
"name": "Game Studio Inc",
"slug": "game-studio",
"description": "Indie game development studio",
"website": "https://gamestudio.com"
}
Get Organization#
Get organization details.
GET /organizations/{organizationId}
Authorization: Bearer <token>
Update Organization#
Update organization details.
PATCH /organizations/{organizationId}
Authorization: Bearer <token>
Content-Type: application/json
{
"name": "Updated Name",
"description": "Updated description"
}
Delete Organization#
Delete an organization (requires owner role).
DELETE /organizations/{organizationId}
Authorization: Bearer <token>
Health Checks#
Basic Health#
GET /health
Response:
{
"status": "healthy",
"timestamp": "2024-01-15T10:30:00Z",
"version": "1.0.0"
}
Readiness#
GET /health/ready
Response:
{
"status": "ready",
"checks": {
"database": "healthy",
"cache": "healthy",
"storage": "healthy"
}
}
Liveness#
GET /health/live
Response:
{
"status": "alive"
}
Webhooks#
Configure webhooks to receive real-time notifications about events in your projects.
Event Types#
| Event | Description |
|---|---|
project.created |
Project was created |
project.updated |
Project was updated |
project.deleted |
Project was deleted |
asset.uploaded |
Asset was uploaded |
asset.updated |
Asset was updated |
asset.deleted |
Asset was deleted |
member.added |
Member was added to project |
member.removed |
Member was removed |
comment.created |
Comment was created |
comment.resolved |
Comment was resolved |
Webhook Payload#
{
"id": "evt_abc123",
"type": "asset.uploaded",
"timestamp": "2024-01-15T10:30:00Z",
"data": {
"projectId": "proj_abc123",
"assetId": "ast_abc123",
"name": "hero_model.fbx",
"uploadedBy": {
"id": "usr_abc123",
"name": "John Doe"
}
}
}
Webhook Signature#
Verify webhook authenticity using the X-Webhook-Signature header:
import crypto from 'crypto';
function verifyWebhook(
payload: string,
signature: string,
secret: string
): boolean {
const expected = crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(`sha256=${expected}`)
);
}
SDK Examples#
TypeScript/JavaScript#
import { YemayaClient } from '@yemaya/sdk';
const client = new YemayaClient({
apiKey: 'yek_live_abc123...',
// or
accessToken: 'eyJhbG...',
});
// List projects
const projects = await client.projects.list({
status: 'active',
limit: 10,
});
// Create project
const project = await client.projects.create({
name: 'My Game',
type: 'game',
});
// Upload asset
const asset = await client.assets.upload(project.id, {
file: fs.readFileSync('model.fbx'),
name: 'Character Model',
folder: 'characters',
});
Python#
from yemaya import YemayaClient
client = YemayaClient(api_key="yek_live_abc123...")
# List projects
projects = client.projects.list(status="active", limit=10)
# Create project
project = client.projects.create(
name="My Game",
type="game"
)
# Upload asset
with open("model.fbx", "rb") as f:
asset = client.assets.upload(
project_id=project.id,
file=f,
name="Character Model",
folder="characters"
)
cURL#
# Authenticate
TOKEN=$(curl -s -X POST https://api.yemaya.io/v1/auth/login \
-H "Content-Type: application/json" \
-d '{"email":"user@example.com","password":"password"}' \
| jq -r '.data.tokens.accessToken')
# List projects
curl -s https://api.yemaya.io/v1/projects \
-H "Authorization: Bearer $TOKEN" \
| jq
# Create project
curl -s -X POST https://api.yemaya.io/v1/projects \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"My Project","type":"game"}'
Error Codes#
| Code | Description | Resolution |
|---|---|---|
AUTH_REQUIRED |
Authentication required | Include valid Authorization header |
INVALID_TOKEN |
Token is invalid or expired | Refresh token or re-authenticate |
INSUFFICIENT_PERMISSIONS |
User lacks required permissions | Request access from project owner |
VALIDATION_ERROR |
Request validation failed | Check error details for field issues |
NOT_FOUND |
Resource not found | Verify resource ID exists |
DUPLICATE_RESOURCE |
Resource already exists | Use different identifier |
RATE_LIMITED |
Too many requests | Wait and retry with backoff |
QUOTA_EXCEEDED |
Storage or usage quota exceeded | Upgrade plan or delete unused resources |
FILE_TOO_LARGE |
Upload exceeds size limit | Compress file or upgrade plan |
UNSUPPORTED_FORMAT |
File format not supported | Convert to supported format |
Specialized Endpoints#
For detailed documentation on specialized API endpoints, see the following guides:
| Documentation | Description |
|---|---|
| 3D Generation | Text-to-3D, image-to-3D, mesh processing, texturing, rigging, animation |
| Audio | Music generation, voice synthesis, sound effects, DAW integration |
| Gameplay | Combat simulation, physics, inventory, quests, dialogue, economy |
| NPC | AI-powered characters, conversations, memory, behavior |
| Creative Tools | Blender, Unreal Engine, Godot, Houdini integration |
| WebSocket | Real-time events, progress tracking, collaboration |
See the full Endpoints Reference for a complete index.