OMSS Overview

A high-level overview of how OMSS works, its endpoints, and core concepts

How OMSS Works

An OMSS-compliant backend exposes a small set of HTTP endpoints. A frontend application queries these endpoints with a TMDB ID (and optionally a platform and provider), and receives back a standardized list of streaming sources and subtitles.

Endpoints at a Glance

Endpoint	Method	Purpose
/ and /v1	GET	Backend info, available media & providers
/v1/movies/{id}	GET	Movie streaming sources by TMDB ID
/v1/tv/{id}/seasons/{s}/episodes/{e}	GET	TV episode streaming sources
/v1/refresh/{id}	POST	Invalidate a cached response by ID

The movie, TV, and refresh endpoints are sunset in OMSS v1.1 and will be removed in the next major version. Backends implementing v1.x must continue to support them for the lifetime of v1.

The platform Parameter

The platform query parameter is a key concept in OMSS:

• web (default): All url fields return proxied, browser-ready URLs with no CORS issues — suitable for HTML5 video players.
• native: Returns the upstream provider URL directly, plus a headers object containing any required HTTP headers (e.g., Referer). For use by native player apps that can handle CORS and custom headers.

Response Structure

Every successful source/subtitle response follows this structure:

{
  "id": "<uuid>",
  "expiresAt": "<ISO 8601 timestamp>",
  "sources": [ ...Source Objects ],
  "subtitles": [ ...Subtitle Objects ],
  "diagnostics": [ ...Warning/Error Objects ]
}

The diagnostics array contains non-fatal warnings about scraping issues (e.g., a provider failed partially) and does not prevent the response from being usable.

Versioning

OMSS uses semantic versioning (MAJOR.MINOR.PATCH) with URL-based version prefixes (/v1/, /v2/). Breaking changes require a new major version. Clients MUST ignore unknown fields to stay forward-compatible.