Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/rivenmedia/riven/llms.txt

Use this file to discover all available pages before exploring further.

The Streaming API provides two real-time communication channels — Server-Sent Events (SSE) for one-way server-to-client pushes and WebSocket for bidirectional messaging — plus a media proxy that streams video files directly from debrid providers. All SSE and proxy routes are prefixed with /api/v1/stream; WebSocket routes use /api/v1/ws.

​
Server-Sent Events (SSE)

SSE lets a client maintain a long-lived HTTP connection and receive events as they occur on the server. Riven publishes events for log output, state changes, item completions, and more.

​
GET /stream/event_types

List all currently registered event type names. The list grows as services start and register their topics. 
curl http://localhost:8080/api/v1/stream/event_types \
  -H "x-api-key: YOUR_KEY"
​
event_types
string[]
Array of event type name strings available to subscribe to.
Example response 
{
  "event_types": ["logging", "state_change", "item_complete"]
}

​
GET /stream/

Subscribe to an event stream. The connection stays open and the server pushes data: lines as events occur. Each data: line is a JSON string.
​
event_type
string
required
The event type to subscribe to. Must be one of the names returned by GET /stream/event_types.
The response uses Content-Type: text/event-stream. Standard auth headers are supported. 
curl -N http://localhost:8080/api/v1/stream/logging \
  -H "x-api-key: YOUR_KEY"
Example event output (logging stream) 
data: {"time":"2024-11-15T12:34:56.789000","level":"INFO","message":"Scraping Breaking Bad S01E01"}

data: {"time":"2024-11-15T12:34:57.123000","level":"DEBUG","message":"Found 8 streams via Torrentio"}
Each SSE event object for the logging topic contains:
​
time
string
ISO 8601 datetime string of when the log record was created.
​
level
string
Log level: DEBUG, INFO, WARNING, ERROR, or CRITICAL.
​
message
string
The log message text.

​
Media proxy

Certain debrid providers require that media files be fetched through a server-side proxy rather than accessed directly by the client. Riven detects this automatically via the PROXY_REQUIRED_PROVIDERS list and routes those requests through the configured proxy.

​
GET /stream/file/

Stream a media file associated with a library item. Range requests (Range headers) are forwarded upstream, enabling seeking in video players. The MIME type is inferred from the file extension rather than relying on the provider’s Content-Type.
​
item_id
integer
required
Internal database ID of the MediaItem to stream.
curl -H "x-api-key: YOUR_KEY" \
     -H "Range: bytes=0-1048575" \
     http://localhost:8080/api/v1/stream/file/42 \
     --output segment.mkv
Returns 404 if the item does not exist, has no media entry, or has no valid stream URL. Returns 502 if the upstream debrid URL cannot be reached.

​
HLS transcoding

Riven can transcode media to HLS segments on the fly using FFmpeg. This is useful for clients that cannot play the source container directly.

​
GET /stream/hls//index.m3u8

Generate an HLS playlist for the specified media item. Each segment references a /segment/{n}.ts endpoint.
​
item_id
integer
required
Internal database ID of the media item.
​
pix_fmt
string
FFmpeg pixel format (e.g. yuv420p). Omit to keep the original.
​
profile
string
H.264 profile (e.g. main, baseline). Omit to keep the original.
​
level
string
H.264 level (e.g. 4.0). Omit to keep the original.
​
resolution
string
Output resolution. Accepts WIDTHxHEIGHT (e.g. 1280x720) or a height shorthand (e.g. 720). Omit to keep the original.
# Original quality playlist
curl "http://localhost:8080/api/v1/stream/hls/42/index.m3u8" \
  -H "x-api-key: YOUR_KEY"

# 720p re-encode playlist
curl "http://localhost:8080/api/v1/stream/hls/42/index.m3u8?resolution=720" \
  -H "x-api-key: YOUR_KEY"

​
GET /stream/hls//segment/.ts

Fetch a single HLS segment. FFmpeg seeks to the correct position and transcodes a 12-second chunk on demand.
​
item_id
integer
required
Internal database ID of the media item.
​
seq
integer
required
Zero-based segment sequence number.
​
pix_fmt
string
FFmpeg pixel format.
​
profile
string
H.264 profile.
​
level
string
H.264 level.
​
resolution
string
Output resolution.
Returns the segment as video/mp2t.

​
WebSocket

The WebSocket endpoint provides real-time bidirectional communication. It publishes the same log events as the SSE logging stream and can be used by dashboard clients for live updates.

​
WS /ws/

Connect to a WebSocket topic. The server pushes JSON-encoded messages whenever an event is published on that topic.
​
topic
string
required
The topic to subscribe to (e.g. logging).
​
api_key
string
required
API key for authentication. WebSocket connections must use the query-parameter method — header-based auth is not supported for WebSocket upgrades.
ws://localhost:8080/api/v1/ws/logging?api_key=YOUR_KEY
JavaScript example 
const ws = new WebSocket(
  "ws://localhost:8080/api/v1/ws/logging?api_key=YOUR_KEY"
);

ws.onmessage = (event) => {
  const logEntry = JSON.parse(event.data);
  console.log(`[${logEntry.level}] ${logEntry.message}`);
};

ws.onerror = (err) => console.error("WebSocket error", err);
Each message pushed to the logging topic is a JSON string with the same shape as the SSE logging events: 
{
  "time": "2024-11-15T12:34:56.789000",
  "level": "INFO",
  "message": "Download complete for Breaking Bad S01E01"
}
The server accepts incoming text messages on the WebSocket connection and logs them at DEBUG level. You can send any valid JSON string from the client side for testing.

​
SSE vs WebSocket

FeatureSSE (/stream/{type})WebSocket (/ws/{topic})
DirectionServer → Client onlyBidirectional
ProtocolHTTP/1.1 keep-aliveWebSocket upgrade
AuthHeader or query paramQuery param only
Browser supportEventSource APIWebSocket API
ReconnectAutomatic (browser)Manual
Use caseDashboards, log tailingInteractive clients

Build docs developers (and LLMs) love

Get started for freeTalk to us