API Reference

The EmProps Job Queue system exposes three distinct APIs for different integration scenarios:

System Architecture

The complete platform consists of:

1. EmProps API (PostgreSQL-backed platform API)

   • Collection and workflow management
   • Job tracking and execution
   • User authentication and credits

2. Job Queue API (Redis-backed queue orchestration)

   • Real-time WebSocket event streaming
   • Job submission and monitoring
   • Worker coordination

3. Internal Communication (Redis pub/sub, webhooks)

   • Event broadcasting across services
   • Worker-to-API communication
   • External system notifications

Integration Flow

EmProps UI (Frontend)
    ↓
EmProps API (REST + SSE)
    ↓
Job Queue API (Redis + WebSocket)
    ↓
Workers (ComfyUI/Ollama/API)
    ↓
Results → EmProps API → UI

API Overview

EmProps REST API

Platform API for collection generation, job management, and workflow execution.

Base URL: https://api.emprops.com (production)

Key Endpoints:

• POST /collections/{id}/generate - Submit collection generation
• GET /jobs/{id} - Get job status
• GET /jobs/{id}/stream - Server-Sent Events for job updates
• POST /workflows/create-simple-collection - Create API-based collections

Job Queue WebSocket API

Real-time event streaming for job monitoring and system status.

WebSocket URL: wss://job-queue-api.railway.app

Event Types:

• Job lifecycle: job_submitted, job_status_changed, complete_job
• Worker status: worker_connected, worker_disconnected
• Machine status: machine_status_updated

Internal APIs

Redis pub/sub channels and webhook delivery for system integration.

Redis Channels:

• job:progress:{jobId} - Job progress updates
• machine:{machineId}:status - Machine status changes
• worker:status:{workerId} - Worker status updates

Webhooks:

• Configurable HTTP callbacks for external systems
• Retry logic with exponential backoff
• Auto-reconnection after failures

Authentication

EmProps API

• Header: user_id (required for user-scoped operations)
• API Keys: X-API-Key header for service-to-service communication
• Dynamic Auth: JWT bearer tokens for OAuth flows

Job Queue API

• Token: Authorization: Bearer {AUTH_TOKEN} (environment variable)
• Purpose: Prevent unauthorized job submission

Key Concepts

Jobs vs Workflows

• Job (PostgreSQL): User request in EmProps API, may contain multiple steps
• Step (Redis): Individual processing unit executed by workers
• Workflow: Sequence of steps with shared context and trace ID

Event Flow

1. User submits generation via EmProps API
2. EmProps API creates job record (PostgreSQL)
3. GeneratorV2 submits steps to Job Queue (Redis)
4. Workers claim and process steps
5. Results flow back through webhooks/Redis
6. EmProps API updates job record
7. UI receives updates via SSE or WebSocket

Error Handling

HTTP Status Codes

• 200 - Success
• 400 - Invalid request (validation error)
• 401 - Unauthorized (missing/invalid auth)
• 403 - Forbidden (insufficient permissions)
• 404 - Resource not found
• 409 - Conflict (duplicate resource)
• 500 - Server error
• 502 - External service error

WebSocket Close Codes

• 1000 - Normal closure
• 1006 - Abnormal closure (connection lost)
• 1008 - Policy violation (auth failure)
• 4000 - Custom: Heartbeat timeout

Rate Limiting

EmProps API

• Job Submission: Based on user credits
• Collection Creation: No hard limit (database constraints apply)
• Job Queries: No limit (read operations)

Job Queue API

• WebSocket Connections: 100 per client (configurable)
• Job Submission: No hard limit (controlled by EmProps API)
• Progress Events: Throttled to 1 per second per job

Next Steps

• REST API Reference - Detailed EmProps API endpoints
• WebSocket API Reference - Real-time event specification
• Internal APIs Reference - Redis and webhook integration