Real-time API

Spooled provides real-time streaming APIs for live updates on jobs, queues, and workers. Choose between WebSocket, SSE, or gRPC streaming based on your needs.

How It Works

Real-time updates are powered by Redis Pub/Sub. When jobs change state, events are published and streamed to connected clients.

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#ecfdf5', 'primaryTextColor': '#065f46', 'primaryBorderColor': '#10b981', 'lineColor': '#6b7280', 'signalColor': '#10b981'}}}%%
sequenceDiagram
  participant C as Client
  participant S as Spooled
  participant R as Redis Pub/Sub

  C->>S: Connect (WS/SSE)
  S->>C: Connected
  C->>S: Subscribe to queue:orders
  S->>R: SUBSCRIBE queue:orders
  
  loop Real-time updates
    R-->>S: Job event
    S-->>C: job.created
    R-->>S: Job event
    S-->>C: job.completed
  end

WebSocket API

Connect to the WebSocket endpoint for real-time bidirectional communication.

Connecting

const ws = new WebSocket('wss://api.spooled.cloud/api/v1/ws');

ws.onopen = () => {
  // Authenticate
  ws.send(JSON.stringify({ 
    type: 'auth', 
    token: 'YOUR_API_KEY' 
  }));
  
  // Subscribe to topics
  ws.send(JSON.stringify({
    type: 'subscribe',
    topics: ['queue:orders', 'queue:payments']
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Event:', data.type, data.payload);
};

Available Topics

Server-Sent Events (SSE)

SSE provides a simpler one-way stream that works through proxies and firewalls. It's ideal for dashboards and monitoring.

Browser Example

const eventSource = new EventSource(
  'https://api.spooled.cloud/api/v1/events?token=YOUR_API_KEY'
);

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Event:', data);
};

eventSource.onerror = (error) => {
  console.error('SSE Error:', error);
};

Using curl

curl -N -H "Accept: text/event-stream" \
  "https://api.spooled.cloud/api/v1/events?token=YOUR_API_KEY"

Query Parameters

Event Types

Job Events

Event Payload Example

{
  "type": "job.completed",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "job_id": "job_abc123",
    "queue": "order-processing",
    "duration_ms": 1234,
    "result": { "order_id": "ord_456" }
  }
}

Queue Events

Connection Limits