> ## Documentation Index
> Fetch the complete documentation index at: https://vyla.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Stream API

> An optional self-hosted HTTP and SSE layer built on top of Vyla SDK.

## Use this only when HTTP is the right boundary

Stream API packages Vyla SDK behind a small Node.js HTTP service. It is useful when a browser, mobile app, or another process needs progressive playback candidates over HTTP. It is not required to use Vyla, and it is not the primary integration for a Node.js application—use [Vyla SDK](/sdk) directly in that case.

The service accepts TMDB IDs, asks configured SDK providers for candidates, verifies results, and emits usable sources as they arrive. A player can start with the first source while retaining later sources as fallbacks.

## What it provides

| Capability | Endpoint family | Why it exists |
| - | - | - |
| Progressive playback | `/movie`, `/tv` | Stream metadata and verified source candidates with SSE |
| Supplemental media | `/subtitles`, `/downloads` | Fetch tracks or downloadable candidates separately |
| Operations | `/health`, `/test`, `/debug` | Check source status and investigate a provider when permitted |

## Start a local instance

```bash theme={null}
git clone https://gitlab.com/vyla-entertainment/stream-api
cd stream-api
npm install
TMDB_API_KEY=your_key
node server.js
```

The default local address is `http://localhost:7860`. For remote access, place the service behind TLS and your own access controls. Full configuration is in [Self-hosting](/self-hosting).

## Lifecycle of a playback request

1. A client opens `/movie?id=:tmdbId` or `/tv?id=:tmdbId&season=:season&episode=:episode`.
2. The API returns an SSE response and emits a `meta` event with title metadata and subtitle tracks when available.
3. Active SDK providers resolve in parallel; verified results arrive as individual `source` events.
4. The server sends `done` after all source attempts finish or time out.

Start the player on the first source. Never wait for `done` before allowing playback, and always retain a fallback queue. See [Paths and events](/stream-api/paths) for the contract.

<Tip>
  If your application is already a Node.js service, call `VylaSDK#getStream`, `getSubtitles`, and `getDownloads` directly. That removes an unnecessary network hop and lets you define your own public API.
</Tip>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.