Skip to main content

​
Overview

The Open Media Streaming Standard (OMSS) defines a standardized HTTP API for media backends. By adhering to the specification, both clients and servers can interoperate without requiring implementation-specific integrations. OMSS specifies:
  • A consistent HTTP API for resolving media sources
  • Standard request and response models
  • Common provider behavior
  • Metadata and source representations
  • Standardized filtering and diagnostics
  • A portable contract that any compliant implementation can expose
Because the API is standardized, any OMSS-compliant client can communicate with any OMSS-compliant server without modification.

​
What’s New in v1.1

OMSS v1.1 builds upon the v1.0 specification while maintaining compatibility with existing implementations. Highlights include:
  • Standardized filter expressions for selecting and excluding sources
  • Diagnostic information to explain provider execution and filtering decisions
  • Platform-aware responses for web and native clients
  • A root endpoint for discovering server capabilities and supported specification versions
  • Improved request validation and standardized error responses
  • Additional metadata fields for sources and subtitles
  • Sunset notices for legacy v1 endpoints
These additions make the specification easier to integrate, debug, and evolve while preserving the core API contract.

​
Core Concepts

Understanding these concepts will help you read the endpoint reference and understand the API.

​
Media IDs

OMSS identifies media using TMDB IDs (The Movie Database identifiers). Movie endpoints require the movie’s TMDB ID. TV episode endpoints require:
  • TMDB show ID
  • Season number
  • Episode number
These identifiers provide a consistent way for providers to resolve media sources across different implementations.

​
Providers

A provider is an implementation responsible for resolving media sources from a particular streaming source. The OMSS specification defines the contract between the server and its providers, but does not prescribe how providers are implemented, discovered, or managed. Different OMSS implementations may use different architectures or technologies while exposing the same external API. For example, an implementation may be written in TypeScript, Python, Go, Rust, or another language—as long as it follows the specification, clients can interact with it in the same way.

​
Sources

A source represents a playable or downloadable media stream returned by one or more providers. A source may include information such as:
  • Stream URL
  • Quality
  • Language
  • Available subtitles
  • Provider metadata
  • Stream characteristics
  • Additional implementation metadata
A single request may return multiple sources originating from multiple providers. The OMSS specification defines the structure of source objects but does not dictate how implementations cache, prioritize, or retrieve them.

​
Filters

OMSS v1.1 introduces filter expressions that allow clients to control which sources are returned. Filters can be used to:
  • Include or exclude providers
  • Filter by quality
  • Match languages
  • Require specific source characteristics
  • Combine multiple conditions using logical expressions
Filtering is standardized so clients can use the same syntax across all compliant servers.

​
Diagnostics

Servers may optionally return diagnostic information describing how a request was processed. Diagnostics can include information such as:
  • Which providers were executed
  • Provider execution results
  • Sources filtered out and why
  • Validation messages
  • Performance information
Diagnostics are intended to help developers understand server behavior without affecting normal client operation.

​
Platforms

OMSS recognizes that different clients have different requirements. The optional platform parameter allows implementations to tailor responses for environments such as:
  • web
  • native
This enables servers to expose sources that are appropriate for a particular client while preserving a consistent API.

​
Proxying & Stream Resolution

Some providers expose streams through intermediary proxy services rather than direct origin URLs. OMSS standardizes the representation of resolved media sources but intentionally leaves proxying, URL unwrapping, caching strategies, authentication handling, and request routing as implementation details. Individual servers may choose to expose original URLs, proxy endpoints, signed URLs, or additional stream processing features.

​
How to Read This Reference

Generated from the specification

Every endpoint in this section is generated directly from the official OMSS v1.1 OpenAPI specification. The reference stays synchronized with the standard rather than relying on manually maintained documentation.

Interactive playground

Each endpoint includes an interactive playground. Configure the server URL to point at any OMSS-compliant implementation and execute requests directly from the documentation.

Implementation-independent

This reference describes the OMSS specification itself—not any particular implementation. Any server conforming to OMSS should expose the same API contract.

Multi-language examples

Every endpoint includes automatically generated examples for JavaScript, cURL, Python, PHP, Go, Java, and additional supported languages.
The playground defaults to http://localhost:{port}. You can change the server URL in the playground to point at any OMSS-compliant implementation.

​
Before You Start

To use this API, you’ll need access to an OMSS-compliant server. Depending on the implementation you choose, additional configuration may be required, such as:
  1. Deploying or connecting to an OMSS server
  2. Configuring provider integrations
  3. Supplying any required API keys or credentials
  4. Enabling one or more providers capable of resolving media sources
Consult your implementation’s documentation for installation and configuration details. Once your server is running, you can begin exploring the API:

Get Movie Sources

Resolve streaming sources for a movie by TMDB ID.

Get TV Episode Sources

Resolve streaming sources for a TV episode using its TMDB show ID, season, and episode.
Last modified on July 24, 2026