---
title: Realtime
url: https://lumean.app/en/developers/docs/realtime
locale: en
description: "WebSocket channels: connection, private channel authorisation and order events."
generated: 2026-10-17
spec_version: 0.0.1
---

# Realtime

WebSocket channels: connection, private channel authorisation and order events.

## Connection

## Public WebSocket API (X-API-KEY)

Real-time order and Cartesia / Fish Audio voice-clone events for Public API clients. The protocol is Pusher-compatible, so
standard libraries work as-is: **pusher-js** or **Laravel Echo**.

### Connecting

Point your client at the server below and set the auth endpoint to
`POST /api/public/broadcasting/auth`, adding the `X-API-KEY` header to its auth
headers. The library performs that request itself on every subscription. The key
permission depends on the channel: order and chunk-preview channels need `orders.read`,
the Cartesia and Fish Audio voice-clone channels need `voices.read`, the reseller gift code channel needs
`reseller.read`.

### Channels

- `private-orders.{userId}` — events for every order of the account. `{userId}` is the
  numeric id of the key owner, returned by `GET /user`.
- `private-order.task.{orderId}` — events for a single order, including live progress.
- `private-chunks.preview.{userId}` — the result of a background chunk-preview calculation.
- `private-cartesia-voice-clones.{userId}` — status changes of your Cartesia voice clones
  (`voice_clone.updated`); a clone in `ready` carries the `voice_id` for a template.
- `private-fishaudio-voice-clones.{userId}` — status changes of your Fish Audio voice clones
  (`voice_clone.updated`); the `voice_id` is a 32-character hex string, not a UUID.
- `private-giftcodes.{userId}` — reseller gift codes and reseller status: `issued` (a batch
  summary), `status.changed` (a code), `reseller.status.changed` and
  `reseller.application.status.changed`. Events carry masked codes only.

Every channel is private: a channel belonging to another account is refused with `403`.

### What this replaces

Subscribing removes the need to poll `GET /orders/{order}`. Wait for the order to reach
a terminal status (`completed`, `result_delivered`, `failed`, `compensated`,
`cancelled`), then request download links via `POST /storage/url`.

Events are delivered at least once and may arrive out of order — treat each one as a
state snapshot rather than a step in a sequence.

- host: `ws.lumean.app`
- port: `443`
- scheme: `wss`
- app key: `7c4dd881d8116ac76fe89aff71d8c2ff`
- auth endpoint: `https://api.lumean.app/api/public/broadcasting/auth`

## Private channel authorisation

`POST /broadcasting/auth` — Authorize WebSocket channel subscription (API key)

## Channels

| Field | Required scope | Events | Page |
| --- | --- | --- | --- |
| `private-orders.{userId}` | `orders.read` | 14 | [orders](https://lumean.app/en/developers/docs/md/realtime/orders) |
| `private-order.task.{orderId}` | `orders.read` | 8 | [order-task](https://lumean.app/en/developers/docs/md/realtime/order-task) |
| `private-chunks.preview.{userId}` | `orders.read` | 1 | [chunks-preview](https://lumean.app/en/developers/docs/md/realtime/chunks-preview) |
| `private-cartesia-voice-clones.{userId}` | `voices.read` | 1 | [cartesia-voice-clones](https://lumean.app/en/developers/docs/md/realtime/cartesia-voice-clones) |
| `private-fishaudio-voice-clones.{userId}` | `voices.read` | 1 | [fishaudio-voice-clones](https://lumean.app/en/developers/docs/md/realtime/fishaudio-voice-clones) |
| `private-giftcodes.{userId}` | `reseller.read` | 4 | [giftcodes](https://lumean.app/en/developers/docs/md/realtime/giftcodes) |

---

- This page in the browser: https://lumean.app/en/developers/docs/realtime
- Full machine-readable reference: https://api.lumean.app/docs/llm.md