Real-time event streaming for generation progress, collaboration, and pipeline monitoring.
Overview#
The WebSocket API provides bidirectional real-time communication for receiving instant updates on long-running operations, collaborative editing, and system events.
WebSocket URL: wss://api.yemaya.io/ws Development URL:
ws://localhost:3000/ws
Connection#
Establishing Connection#
Connect to the WebSocket server with authentication:
const ws = new WebSocket('wss://api.yemaya.io/ws?token=YOUR_JWT_TOKEN');
ws.onopen = () => {
console.log('Connected to Yemaya WebSocket');
};
ws.onmessage = (event) => {
const message = JSON.parse(event.data);
handleMessage(message);
};
ws.onerror = (error) => {
console.error('WebSocket error:', error);
};
ws.onclose = (event) => {
console.log('WebSocket closed:', event.code, event.reason);
};
Authentication#
Include your JWT token as a query parameter:
wss://api.yemaya.io/ws?token=eyJhbGciOiJIUzI1NiIs...
Or pass userId for anonymous connections (limited functionality):
wss://api.yemaya.io/ws?userId=user_abc123
REST Endpoints#
Get Connection Info#
GET /ws/info
Response:
{
"success": true,
"data": {
"url": "wss://api.yemaya.io/ws",
"protocols": ["json"],
"version": "1.0.0",
"authentication": {
"method": "query_param",
"param": "token",
"type": "jwt"
},
"channels": [
{
"name": "job",
"description": "Subscribe to job-specific events",
"events": [
"generation:progress",
"generation:complete",
"generation:failed"
]
},
{
"name": "project",
"description": "Subscribe to project-wide events",
"events": ["phase:*", "quality:*", "pipeline:*"]
}
]
}
}
Get Server Statistics#
GET /ws/stats
Authorization: Bearer <token>
Response:
{
"success": true,
"data": {
"totalConnections": 150,
"authenticatedConnections": 120,
"totalSubscriptions": 420,
"channelStats": {
"job": 45,
"project": 30,
"collaboration": 75,
"pipeline": 20
}
}
}
Get Presence#
Get users present on a specific resource.
GET /ws/presence/{channel}/{resourceId}
Authorization: Bearer <token>
Response:
{
"success": true,
"data": {
"channel": "collaboration",
"resourceId": "doc_abc123",
"users": [
{
"connectionId": "conn_123",
"userId": "usr_abc",
"metadata": { "userAgent": "Chrome/120" }
}
],
"count": 1
}
}
Message Protocol#
Message Format#
All messages follow this structure:
{
"type": "message_type",
"timestamp": "2024-01-15T10:00:00.000Z",
"requestId": "optional_correlation_id",
...additional fields
}
Client Messages#
Subscribe#
Subscribe to events for a resource.
{
"type": "subscribe",
"timestamp": "2024-01-15T10:00:00.000Z",
"channel": "job",
"resourceId": "job_3d_abc123",
"events": ["generation:progress", "generation:complete", "generation:failed"]
}
Channels:
| Channel | Description | Resource ID |
|---|---|---|
job |
Generation/training jobs | Job ID |
project |
Project-wide events | Project ID |
asset |
Asset lock/edit events | Asset ID |
collaboration |
Real-time collaboration | Document/Resource ID |
pipeline |
Pipeline execution events | Pipeline ID |
agent |
Agent activity events | Agent/Task ID |
user |
User-specific notifications | User ID |
Unsubscribe#
{
"type": "unsubscribe",
"timestamp": "2024-01-15T10:00:00.000Z",
"channel": "job",
"resourceId": "job_3d_abc123"
}
Ping#
Keep connection alive (recommended every 30 seconds):
{
"type": "connection:ping",
"timestamp": "2024-01-15T10:00:00.000Z"
}
Server Messages#
Connection Opened#
{
"type": "connection:open",
"timestamp": "2024-01-15T10:00:00.000Z",
"connectionId": "conn_abc123"
}
Subscription Confirmed#
{
"type": "subscription:confirm",
"timestamp": "2024-01-15T10:00:00.000Z",
"channel": "job",
"resourceId": "job_3d_abc123",
"subscriptionId": "sub_xyz789"
}
Pong#
{
"type": "connection:pong",
"timestamp": "2024-01-15T10:00:00.000Z"
}
Event Types#
Generation Events#
generation:progress#
{
"type": "generation:progress",
"timestamp": "2024-01-15T10:00:30.000Z",
"jobId": "job_3d_abc123",
"jobType": "text_to_3d",
"progress": 45,
"stage": "generating_mesh",
"message": "Creating base geometry...",
"estimatedSecondsRemaining": 65,
"metadata": {
"polyCount": 12000,
"currentOperation": "subdivision"
}
}
generation:complete#
{
"type": "generation:complete",
"timestamp": "2024-01-15T10:01:35.000Z",
"jobId": "job_3d_abc123",
"jobType": "text_to_3d",
"resultUrl": "https://cdn.yemaya.io/3d/job_3d_abc123/model.glb",
"previewUrl": "https://cdn.yemaya.io/3d/job_3d_abc123/thumb.png",
"processingTime": 95000,
"metadata": {
"polyCount": 45000,
"textureCount": 3
}
}
generation:failed#
{
"type": "generation:failed",
"timestamp": "2024-01-15T10:01:00.000Z",
"jobId": "job_3d_abc123",
"jobType": "text_to_3d",
"error": {
"code": "GENERATION_FAILED",
"message": "Model generation failed due to invalid prompt",
"details": { "reason": "safety_filter" }
},
"retryable": true
}
Queue Events#
queue:position#
{
"type": "queue:position",
"timestamp": "2024-01-15T10:00:00.000Z",
"jobId": "job_3d_abc123",
"position": 3,
"totalInQueue": 15,
"estimatedWaitSeconds": 180
}
queue:eta#
{
"type": "queue:eta",
"timestamp": "2024-01-15T10:00:00.000Z",
"jobId": "job_3d_abc123",
"estimatedStartTime": "2024-01-15T10:03:00.000Z",
"estimatedCompletionTime": "2024-01-15T10:05:30.000Z",
"confidence": 0.85
}
Training Events#
training:progress#
{
"type": "training:progress",
"timestamp": "2024-01-15T10:00:00.000Z",
"jobId": "job_train_abc123",
"trainingType": "gaussian_splatting",
"currentIteration": 5000,
"totalIterations": 30000,
"progress": 16.7,
"elapsedSeconds": 1200,
"estimatedSecondsRemaining": 6000
}
training:metrics#
{
"type": "training:metrics",
"timestamp": "2024-01-15T10:00:00.000Z",
"jobId": "job_train_abc123",
"iteration": 5000,
"metrics": {
"loss": 0.0234,
"psnr": 28.5,
"ssim": 0.92,
"lpips": 0.08,
"learningRate": 0.0001,
"numGaussians": 250000
}
}
training:checkpoint#
{
"type": "training:checkpoint",
"timestamp": "2024-01-15T10:00:00.000Z",
"jobId": "job_train_abc123",
"checkpointId": "ckpt_5000",
"iteration": 5000,
"loss": 0.0234,
"checkpointUrl": "https://cdn.yemaya.io/checkpoints/ckpt_5000.ply"
}
Render Events#
render:progress#
{
"type": "render:progress",
"timestamp": "2024-01-15T10:00:00.000Z",
"jobId": "job_render_abc123",
"renderType": "video",
"currentFrame": 120,
"totalFrames": 300,
"progress": 40,
"fps": 2.5,
"estimatedSecondsRemaining": 72
}
render:frame#
{
"type": "render:frame",
"timestamp": "2024-01-15T10:00:00.000Z",
"jobId": "job_render_abc123",
"frameNumber": 120,
"frameUrl": "https://cdn.yemaya.io/frames/frame_0120.png",
"renderTimeMs": 400
}
Collaboration Events#
lock:acquired#
{
"type": "lock:acquired",
"timestamp": "2024-01-15T10:00:00.000Z",
"resourceType": "asset",
"resourceId": "ast_abc123",
"userId": "usr_def456",
"userName": "John Doe",
"lockType": "exclusive",
"expiresAt": "2024-01-15T10:30:00.000Z"
}
lock:released#
{
"type": "lock:released",
"timestamp": "2024-01-15T10:00:00.000Z",
"resourceType": "asset",
"resourceId": "ast_abc123",
"userId": "usr_def456"
}
edit:update#
Real-time edit operation (for collaborative editing):
{
"type": "edit:update",
"timestamp": "2024-01-15T10:00:00.000Z",
"resourceType": "script",
"resourceId": "scr_abc123",
"userId": "usr_def456",
"userName": "John Doe",
"operation": {
"type": "insert",
"path": "scenes[0].dialogue[5].text",
"value": "Hello, world!",
"range": { "start": 45, "end": 45 }
},
"version": 127
}
presence:join#
{
"type": "presence:join",
"timestamp": "2024-01-15T10:00:00.000Z",
"resourceId": "doc_abc123",
"user": {
"id": "usr_def456",
"name": "John Doe",
"avatarUrl": "https://...",
"color": "#FF5733"
}
}
presence:leave#
{
"type": "presence:leave",
"timestamp": "2024-01-15T10:00:00.000Z",
"resourceId": "doc_abc123",
"userId": "usr_def456"
}
cursor:move#
{
"type": "cursor:move",
"timestamp": "2024-01-15T10:00:00.000Z",
"resourceId": "doc_abc123",
"userId": "usr_def456",
"userName": "John Doe",
"color": "#FF5733",
"position": {
"line": 42,
"column": 15
}
}
Pipeline Events#
phase:started#
{
"type": "phase:started",
"timestamp": "2024-01-15T10:00:00.000Z",
"projectId": "proj_abc123",
"phaseId": "phase_concept",
"phaseName": "Concept Development",
"phaseType": "pre_production",
"totalTasks": 15
}
phase:progress#
{
"type": "phase:progress",
"timestamp": "2024-01-15T10:00:00.000Z",
"projectId": "proj_abc123",
"phaseId": "phase_concept",
"phaseName": "Concept Development",
"progress": 60,
"completedTasks": 9,
"totalTasks": 15,
"currentTask": "Generate character concepts"
}
quality:passed#
{
"type": "quality:passed",
"timestamp": "2024-01-15T10:00:00.000Z",
"projectId": "proj_abc123",
"phaseId": "phase_concept",
"gateId": "gate_visual_quality",
"gateName": "Visual Quality Check",
"score": 0.92,
"threshold": 0.85,
"checksPassed": 12,
"checksTotal": 12
}
quality:failed#
{
"type": "quality:failed",
"timestamp": "2024-01-15T10:00:00.000Z",
"projectId": "proj_abc123",
"phaseId": "phase_concept",
"gateId": "gate_visual_quality",
"gateName": "Visual Quality Check",
"score": 0.72,
"threshold": 0.85,
"issues": [
{
"severity": "error",
"description": "Character proportions inconsistent",
"location": "character_hero.png",
"suggestion": "Regenerate with stricter proportion constraints"
}
],
"canOverride": true
}
Agent Events#
agent:started#
{
"type": "agent:started",
"timestamp": "2024-01-15T10:00:00.000Z",
"projectId": "proj_abc123",
"taskId": "task_abc123",
"agentType": "script_writer",
"agentName": "Script Writer Agent",
"taskName": "Write opening scene dialogue"
}
agent:progress#
{
"type": "agent:progress",
"timestamp": "2024-01-15T10:00:00.000Z",
"projectId": "proj_abc123",
"taskId": "task_abc123",
"agentType": "script_writer",
"progress": 45,
"activity": "Drafting dialogue for scene 1",
"tokensUsed": 1250
}
agent:output#
{
"type": "agent:output",
"timestamp": "2024-01-15T10:00:00.000Z",
"projectId": "proj_abc123",
"taskId": "task_abc123",
"agentType": "script_writer",
"outputType": "text",
"preview": "INT. CASTLE THRONE ROOM - NIGHT\n\nThe King sits alone...",
"fullOutputUrl": "https://cdn.yemaya.io/outputs/script_draft.txt"
}
JavaScript SDK Example#
class YemayaWebSocket {
constructor(token) {
this.token = token;
this.ws = null;
this.subscriptions = new Map();
this.reconnectAttempts = 0;
this.maxReconnectAttempts = 5;
}
connect() {
return new Promise((resolve, reject) => {
this.ws = new WebSocket(`wss://api.yemaya.io/ws?token=${this.token}`);
this.ws.onopen = () => {
console.log('Connected');
this.reconnectAttempts = 0;
this.startPingInterval();
resolve();
};
this.ws.onmessage = (event) => {
const message = JSON.parse(event.data);
this.handleMessage(message);
};
this.ws.onclose = (event) => {
this.handleClose(event);
};
this.ws.onerror = reject;
});
}
subscribe(channel, resourceId, events, callback) {
const key = `${channel}:${resourceId}`;
this.subscriptions.set(key, callback);
this.send({
type: 'subscribe',
timestamp: new Date().toISOString(),
channel,
resourceId,
events,
});
}
unsubscribe(channel, resourceId) {
const key = `${channel}:${resourceId}`;
this.subscriptions.delete(key);
this.send({
type: 'unsubscribe',
timestamp: new Date().toISOString(),
channel,
resourceId,
});
}
handleMessage(message) {
if (message.type === 'connection:pong') return;
// Route to appropriate subscription handler
for (const [key, callback] of this.subscriptions) {
if (message.jobId || message.resourceId || message.projectId) {
callback(message);
}
}
}
send(data) {
if (this.ws?.readyState === WebSocket.OPEN) {
this.ws.send(JSON.stringify(data));
}
}
startPingInterval() {
this.pingInterval = setInterval(() => {
this.send({
type: 'connection:ping',
timestamp: new Date().toISOString(),
});
}, 30000);
}
handleClose(event) {
clearInterval(this.pingInterval);
if (this.reconnectAttempts < this.maxReconnectAttempts) {
this.reconnectAttempts++;
setTimeout(() => this.connect(), 1000 * this.reconnectAttempts);
}
}
disconnect() {
clearInterval(this.pingInterval);
this.ws?.close();
}
}
// Usage
const ws = new YemayaWebSocket('your_jwt_token');
await ws.connect();
// Subscribe to generation progress
ws.subscribe(
'job',
'job_3d_abc123',
['generation:progress', 'generation:complete'],
(event) => {
console.log(`Progress: ${event.progress}%`);
}
);
Error Handling#
Connection Errors#
| Code | Description |
|---|---|
4001 |
Authentication failed |
4002 |
Token expired |
4003 |
Invalid subscription |
4004 |
Rate limited |
4005 |
Resource not found |
Error Message#
{
"type": "connection:error",
"timestamp": "2024-01-15T10:00:00.000Z",
"error": "Invalid authentication token",
"code": 4001
}
Best Practices#
- Reconnection: Implement exponential backoff for reconnections
- Ping/Pong: Send ping every 30 seconds to keep connection alive
- Subscription Management: Track subscriptions and resubscribe after reconnection
- Error Handling: Handle all error types gracefully
- Resource Cleanup: Unsubscribe when no longer needed to reduce server load