# WebSockets & Real-Time Events

Imago uses WebSockets and Redis Pub/Sub to provide real-time updates for asynchronous tasks (e.g. image OCR, EXIF extraction, AI summarization).

## Endpoints

All WebSockets endpoints wait for events from the `arq` queue. They require an authentication token to be passed via the `token` query parameter.

### 1. Per-Image Pipeline Events
**Endpoint:** `ws://localhost:8000/ws/pipeline/{image_id}?token=YOUR_API_KEY`

This endpoint streams events related to a specific image. If the image is already fully processed when you connect, the server will immediately yield an artificial `{"event": "pipeline.done", "status": "completed"}` event and the connection may close, ensuring you never miss the final state.

**Required Scopes:** `images:read` AND the image must belong to the client (unless the client is an Admin).

#### Example Events
```json
{"event": "pipeline.started"}
{"event": "task.exif.started"}
{"event": "task.exif.done"}
{"event": "pipeline.done", "status": "completed"}
```

### 2. Global Admin Monitor
**Endpoint:** `ws://localhost:8000/ws/admin/monitor?token=YOUR_ADMIN_KEY`

This endpoint streams high-level pipeline events (start, done, error) for ALL images across the system. It is meant for admin dashboards to display live activity feeds.

**Required Scopes:** `admin`

## Event Buffering

If your client disconnects and reconnects briefly, it might miss events. Imago buffers the last 10 events for each active image pipeline in Redis with a 60-second TTL. When a client connects to the per-image endpoint, any buffered events that were recorded before the WebSocket fully opened are immediately flushed down the socket, enabling seamless UI updates.