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

# 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.

```mermaid theme={"theme":"material-theme-darker"}
sequenceDiagram
    participant Frontend
    participant Backend as OMSS Backend
    participant Providers as Providers

    Frontend->>Backend: GET /v1/movies/{tmdbId}
    activate Backend

    Backend->>Providers: Request providers (out of scope)
    activate Providers
    Providers-->>Backend: Sources + subtitles
    deactivate Providers

    Backend-->>Frontend: 200 OK<br/>{ sources: [...], subtitles: [...] }
    deactivate Backend
```

## 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        |

<Note>
  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.
</Note>

## 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:

```json theme={"theme":"material-theme-darker"}
{
  "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.