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

# Streaming sources for a TV episode

> Retrieve all available streaming sources and subtitles for a TV episode by TMDB series ID, 
season number, and episode number.

**Requirements:**
- Season number: 0–99 (0 = specials)
- Episode number: 1–9,999
- Returns sources with URLs, quality, audio tracks, and provider information
- Returns subtitles with URLs, labels, and formats
- Uses proxy paths for all URL fields
- Includes a unique responseId and expiration timestamp


<Warning>This endpoint has been sunset. It will be removed in the next major version of the spec.</Warning>


## OpenAPI

````yaml get /v1/tv/{id}/seasons/{s}/episodes/{e}
openapi: 3.0.0
info:
  title: Open Media Streaming Specification (OMSS)
  description: >
    A standardized REST API specification for streaming backends to expose
    movies, TV episodes, 

    sources, and subtitles. OMSS enables interoperability between streaming
    backends and frontends.


    **Key Features:**

    - Standardized endpoints for movies and TV episodes

    - Proxy-based source delivery with header support

    - Multi-language and multi-quality source support

    - Subtitle support with multiple formats

    - Diagnostic reporting for partial scrapes

    - Caching optimization recommendations

    - HTTPS-enforced security


    **Reference Implementation:** https://github.com/omss-spec/omss-spec
  version: 1.0.0
  license:
    name: MIT License
    url: https://github.com/omss-spec/omss-spec/blob/main/LICENSE
  contact:
    name: OMSS Community
    url: https://github.com/omss-spec/omss-spec
servers:
  - url: https://api.example.com
    description: Production server (HTTPS required)
    variables:
      version:
        default: v1
        enum:
          - v1
  - url: http://localhost:3000
    description: Development server (localhost only)
security: []
tags:
  - name: Content
    description: Retrieve sources for movies and TV shows
  - name: Proxy
    description: Proxy endpoint to play content by upstream providers
  - name: Health
    description: Health and version information. All endpoints return the same object.
  - name: Refresh
    description: Refresh cached sources
paths:
  /v1/tv/{id}/seasons/{s}/episodes/{e}:
    get:
      tags:
        - Content
      summary: Get streaming sources for a TV episode
      description: >
        Retrieve all available streaming sources and subtitles for a TV episode
        by TMDB series ID, 

        season number, and episode number.


        **Requirements:**

        - Season number: 0–99 (0 = specials)

        - Episode number: 1–9,999

        - Returns sources with URLs, quality, audio tracks, and provider
        information

        - Returns subtitles with URLs, labels, and formats

        - Uses proxy paths for all URL fields

        - Includes a unique responseId and expiration timestamp
      operationId: getTvEpisode
      parameters:
        - name: id
          in: path
          required: true
          description: TMDB series ID (numeric, max 20 characters)
          schema:
            type: string
            pattern: ^\d{1,20}$
          example: '1396'
        - name: s
          in: path
          required: true
          description: Season number (0–99, where 0 is specials)
          schema:
            type: integer
            minimum: 0
            maximum: 99
          example: 1
        - name: e
          in: path
          required: true
          description: Episode number (1–9,999)
          schema:
            type: integer
            minimum: 1
            maximum: 9999
          example: 1
      responses:
        '200':
          description: Streaming sources and subtitles found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceResponse'
              example:
                responseId: e7f2c8d1-9a3b-4c5e-8f1d-2a6b9c4e7f3a
                expiresAt: '2026-01-15T20:30:00Z'
                sources:
                  - id: src_tv_001
                    url: >-
                      /v1/proxy?data=%7B%22url%22%3A%22https%3A%2F%2Fstreaming.provider.com%2Fbreaking-bad%2Fs01e01.m3u8%22%7D
                    type: hls
                    quality: 1080p
                    audioTracks:
                      - language: en
                        label: English
                      - language: es
                        label: Spanish
                      - language: de
                        label: German
                    provider:
                      id: prov_streaming
                      name: Streaming Provider
                subtitles:
                  - url: >-
                      /v1/proxy?data=%7B%22url%22%3A%22https%3A%2F%2Fsubs.provider.com%2Fbb-s01e01-en.vtt%22%7D
                    label: English
                    format: vtt
                diagnostics: []
        '400':
          description: Invalid season or episode number
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: INVALID_EPISODE
                  message: Episode number is out of valid range for this season
                  details:
                    tmdbId: '1396'
                    season: 99
                    episode: 500
                    maxSeason: 5
                    maxEpisodeForSeason: 16
                traceId: 8b9c0d1e-2f3a-4b5c-6d7e-8f9a0b1c2d3e
        '404':
          description: Episode not found or no sources available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    SourceResponse:
      type: object
      required:
        - responseId
        - expiresAt
        - sources
        - subtitles
        - diagnostics
      properties:
        responseId:
          type: string
          format: uuid
          description: Unique identifier for this response (UUID v4)
          example: bdfa40a7-a468-461c-8563-7a0c165f252c
        expiresAt:
          type: string
          format: date-time
          description: |
            ISO 8601 timestamp when sources expire and cache is invalidated.
            Recommended default: 2 hours from response time for sources.
          example: '2026-01-15T18:00:00Z'
        sources:
          type: array
          description: Array of available streaming sources
          items:
            $ref: '#/components/schemas/Source'
          minItems: 0
        subtitles:
          type: array
          description: Array of available subtitles
          items:
            $ref: '#/components/schemas/Subtitle'
          minItems: 0
        diagnostics:
          type: array
          description: >
            Optional diagnostics for partial scrapes, warnings, or metadata
            inferred from filenames.

            Useful for understanding why certain fields may have incomplete or
            inferred values.
          items:
            $ref: '#/components/schemas/Diagnostic'
          minItems: 0
    ErrorResponse:
      type: object
      required:
        - error
        - traceId
      properties:
        error:
          $ref: '#/components/schemas/ErrorObject'
        traceId:
          type: string
          format: uuid
          description: Unique trace ID for error tracking and debugging
          example: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
    Source:
      type: object
      required:
        - id
        - url
        - type
        - quality
        - audioTracks
        - provider
      properties:
        url:
          type: string
          description: |
            Proxy path to the streaming URL (not direct upstream URL).
            Format: `/v1/proxy?data={encodeURIComponent_encoded_json}`
          example: >-
            /v1/proxy?data=%7B%22url%22%3A%22https%3A%2F%2Fcdn.example.com%2Fstream.m3u8%22%7D
        type:
          type: string
          enum:
            - hls
            - dash
            - http
            - mp4
            - mkv
            - webm
          description: Stream type/format
        quality:
          type: string
          description: >
            Video quality/resolution. Common values: "unknown", "360p", "480p",
            "720p", "1080p", "2160p".

            May be inferred from filename or manifest if unavailable. Not
            standardized!
          example: 1080p
        audioTracks:
          type: array
          description: Available audio tracks for this source
          items:
            $ref: '#/components/schemas/AudioTrack'
          minItems: 1
        provider:
          $ref: '#/components/schemas/Provider'
    Subtitle:
      type: object
      required:
        - url
        - label
        - format
      properties:
        url:
          type: string
          description: |
            Proxy path to the subtitle file (not direct upstream URL).
            Format: `/v1/proxy?data={encodeURIComponent_encoded_json}`
          example: >-
            /v1/proxy?data=%7B%22url%22%3A%22https%3A%2F%2Fcdn.example.com%2Fsub.vtt%22%7D
        label:
          type: string
          description: Human-readable subtitle label
          example: English
        format:
          type: string
          enum:
            - vtt
            - srt
            - ass
            - ssa
          description: Subtitle file format
          example: vtt
    Diagnostic:
      type: object
      required:
        - code
        - message
        - severity
      properties:
        code:
          type: string
          description: Machine-readable diagnostic code
          enum:
            - QUALITY_INFERRED
            - LANGUAGE_INFERRED
            - TYPE_INFERRED
            - SUBTITLE_LABEL_INFERRED
            - PROVIDER_ERROR
            - PARTIAL_SCRAPE
          example: QUALITY_INFERRED
        message:
          type: string
          description: Human-readable diagnostic message
          example: Quality for source 'src_tv_002' was inferred from filename
        field:
          type: string
          description: >-
            JSON path to the field this diagnostic relates to (empty string if
            not field-specific)
          example: sources.quality
        severity:
          type: string
          enum:
            - info
            - warning
            - error
          description: Severity level of the diagnostic
          example: warning
    ErrorObject:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: Machine-readable error code
          enum:
            - INVALID_TMDB_ID
            - INVALID_PARAMETER
            - MISSING_PARAMETER
            - INVALID_SEASON
            - INVALID_EPISODE
            - INVALID_RESPONSE_ID
            - RESPONSE_ID_NOT_FOUND
            - NO_SOURCES_AVAILABLE
            - ENDPOINT_NOT_FOUND
            - METHOD_NOT_ALLOWED
            - INTERNAL_ERROR
            - UNSUPPORTED_MEDIA_TYPE
          example: INVALID_TMDB_ID
        message:
          type: string
          description: Human-readable error message
          example: TMDB ID must be numeric
        details:
          type: object
          description: Additional error details (backend-specific, optional)
          example:
            parameter: id
            value: not-a-number
            expected: numeric string
    AudioTrack:
      type: object
      required:
        - language
        - label
      properties:
        language:
          type: string
          description: |
            ISO 639-1 language code (e.g., "en", "es", "de").
            May be inferred or defaulted to "en" if unavailable.
          example: en
        label:
          type: string
          description: Human-readable audio track label
          example: English
    Provider:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: string
          description: Unique identifier for the provider (internal use)
          example: prov_1
        name:
          type: string
          description: Human-readable provider name
          example: Provider One

````