StreamFire API Reference

A self-hosted HLS streaming proxy that aggregates sources from multiple providers. All endpoints return JSON. Video segments are proxied through Cloudflare Workers for reliability.

Base URL https://caribbeantiger-stream.hf.space

Authentication

All endpoints except /health, /docs, and /api/auth/token require a valid JWT in the Authorization header.

Authorization header — Include Authorization: Bearer <access_token> on every request.
POST

/api/auth/token

Authenticate with email and password. Returns a JWT access token valid for 1 hour.

Body fieldTypeDescription
grant_typestringrequired"password" for login, "refresh_token" to renew
emailstringrequired*User email — required when grant_type is password
passwordstringrequired*User password
refresh_tokenstringrequired*Refresh token — required when grant_type is refresh_token
REQUEST — Login
POST /api/auth/token
Content-Type: application/json

{
  "grant_type": "password",
  "email":      "user@example.com",
  "password":   "••••••••"
}
RESPONSE 200
{
  "access_token":  "eyJhbGciOiJFUzI1Ni...",
  "refresh_token": "v1.xyz...",
  "expires_in":    3600,
  "token_type":    "bearer"
}
REQUEST — Refresh
POST /api/auth/token
Content-Type: application/json

{
  "grant_type":    "refresh_token",
  "refresh_token": "v1.xyz..."
}

Get Stream Sources

Resolves HLS stream URLs for a movie or TV episode from multiple providers simultaneously. Returns encrypted proxy URLs ready for playback.

GET

/api/stream

ParameterTypeDescription
idnumberrequiredTMDB ID of the movie or TV show
typestringrequiredmovie or tv
seasonnumberoptionalSeason number — required when type is tv
episodenumberoptionalEpisode number — required when type is tv
audiostringoptional1 to detect audio languages (slower). Default: 0
REQUEST — Movie
GET /api/stream?id=27205&type=movie
Authorization: Bearer eyJhbGciOiJFUzI1Ni...
REQUEST — TV Episode
GET /api/stream?id=66732&type=tv&season=1&episode=1
Authorization: Bearer eyJhbGciOiJFUzI1Ni...
RESPONSE 200
{
  "sources": [
    {
      "url":          "https://streamfire.workers.dev/proxy?d=...",
      "provider":     "peach-wolf",
      "label":        "1080p",
      "qualityLabel": "1080p",
      "maxHeight":    1080,
      "mediaType":    "hls",
      "languages":    ["en"]
    }
  ],
  "subtitles": [...],
  "stats": { "total": 9, "nativeWorking": 4 }
}

HLS Proxy

Fetches upstream HLS content and rewrites manifests for CORS-safe browser playback. URLs are AES-256-GCM encrypted — never construct them manually.

Do not call /proxy directly. The url field in every source returned by /api/stream is already a fully signed, encrypted proxy URL pointing to the Cloudflare Worker.

Now Playing

GET

/api/tmdb/latest

Movies currently in theaters, sorted by popularity.

ParameterTypeDescription
pagenumberoptionalDefault: 1
REQUEST
GET /api/tmdb/latest
Authorization: Bearer ...

Movie Details

GET

/api/tmdb/movie

Full details including cast, genres, runtime, and external IDs (IMDB).

ParameterTypeDescription
idnumberrequiredTMDB movie ID
REQUEST
GET /api/tmdb/movie?id=27205
Authorization: Bearer ...
RESPONSE 200
{
  "id": 27205, "title": "Inception",
  "runtime": 148, "imdb_id": "tt1375666",
  "genres": [{ "id": 28, "name": "Action" }],
  "cast": [{ "name": "Leonardo DiCaprio", "character": "Cobb" }],
  "overview": "...", "vote_average": 8.4
}

Movie Recommendations

GET

/api/tmdb/movie/recommendations

ParameterTypeDescription
idnumberrequiredTMDB movie ID
REQUEST
GET /api/tmdb/movie/recommendations?id=27205
Authorization: Bearer ...

TV Show Details

GET

/api/tmdb/tv

Full details including all seasons, cast, genres, and status.

ParameterTypeDescription
idnumberrequiredTMDB TV show ID
REQUEST
GET /api/tmdb/tv?id=66732
Authorization: Bearer ...
RESPONSE 200
{
  "id": 66732, "title": "Stranger Things",
  "media_type": "tv", "status": "Ended",
  "number_of_seasons": 5, "number_of_episodes": 42,
  "seasons": [{
    "season_number": 1, "name": "Season 1",
    "episode_count": 8, "air_date": "2016-07-13"
  }],
  "cast": [{ "name": "Millie Bobby Brown", "character": "Eleven" }]
}

Season Episodes

GET

/api/tmdb/tv/season

All episodes for a specific season with stills, runtimes, and overviews.

ParameterTypeDescription
idnumberrequiredTMDB TV show ID
seasonnumberrequiredSeason number (1-based)
REQUEST
GET /api/tmdb/tv/season?id=66732&season=1
Authorization: Bearer ...
RESPONSE 200
{
  "season_number": 1, "name": "Season 1",
  "episodes": [{
    "episode_number": 1,
    "name": "Chapter One: The Vanishing of Will Byers",
    "runtime": 48, "vote_average": 8.5,
    "still": "https://image.tmdb.org/t/p/w300/..."
  }]
}

Cast & Crew

GET

/api/tmdb/cast

ParameterTypeDescription
idnumberrequiredTMDB ID
typestringrequiredmovie or tv
REQUEST
GET /api/tmdb/cast?id=27205&type=movie
Authorization: Bearer ...
RESPONSE 200
{
  "cast": [{ "id": 6193, "name": "Leonardo DiCaprio", "character": "Cobb", "profile": "https://..." }],
  "crew": [{ "name": "Christopher Nolan", "job": "Director" }]
}

Images & Logos

GET

/api/tmdb/images

Returns logos (PNG/SVG) for use in hero sections. Logos are filtered to English language by default.

ParameterTypeDescription
idnumberrequiredTMDB ID
typestringrequiredmovie or tv
REQUEST
GET /api/tmdb/images?id=66732&type=tv
Authorization: Bearer ...
RESPONSE 200
{
  "logos": [{
    "url":      "https://image.tmdb.org/t/p/original/...",
    "url_w300": "https://image.tmdb.org/t/p/w300/...",
    "aspect_ratio": 3.14, "language": "en"
  }]
}

TV Networks

GET

/api/tmdb/networks

Popular streaming networks with white-filtered logo URLs.

REQUEST
GET /api/tmdb/networks
Authorization: Bearer ...
RESPONSE 200
{
  "networks": [{ "id": 213, "name": "Netflix", "logo": "https://..." }]
}
GET

/api/tmdb/network/shows

ParameterTypeDescription
idnumberrequiredNetwork ID — e.g. Netflix=213, HBO=49, Prime=1024, Disney+=2739
pagenumberoptionalDefault: 1
REQUEST
GET /api/tmdb/network/shows?id=213&page=1
Authorization: Bearer ...

List Subtitles

GET

/api/subtitles

Returns available subtitle files from OpenSubtitles for a title.

ParameterTypeDescription
idnumberrequiredTMDB ID
typestringoptionalmovie or tv. Default: movie
seasonnumberoptionalFor TV episodes
episodenumberoptionalFor TV episodes
REQUEST
GET /api/subtitles?id=27205&type=movie
Authorization: Bearer ...

Subtitle Proxy

GET

/api/subtitle

Proxies a subtitle file with CORS headers. Automatically converts SRT to WebVTT. Supports timing offset adjustment.

ParameterTypeDescription
urlstringrequiredSubtitle file URL (SRT or VTT)
offsetnumberoptionalTime offset in seconds (e.g. -1.5 to shift back)
REQUEST
GET /api/subtitle?url=https%3A%2F%2Fexample.com%2Fsubs.srt&offset=-1
Authorization: Bearer ...