> ## 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. # Movie sources > Retrieve movie streaming sources by TMDB movie ID. ## OpenAPI ````yaml https://raw.githubusercontent.com/omss-spec/omss-spec/refs/heads/main/spec/v1.1/omss-v1.1.yml get /v1/movies/{id} openapi: 3.1.0 info: title: Open Media Streaming Specification (OMSS) description: > OMSS (Open Media Streaming Specification) v1.1 defines a unified REST API standard for streaming media backends. It enables any frontend application to work with any OMSS-compliant backend through standardized endpoints for retrieving streaming sources and subtitles for TMDB media identifiers. **Key Features:** - Standardized endpoints for movies and TV episodes - Multi-language and multi-quality source support - Subtitle support with multiple formats - Diagnostic reporting for partial scrapes **OMSS Framework:** [github.com/omss-spec/framework](https://github.com/omss-spec/framework) **OMSS Template:** [github.com/omss-spec/template](https://github.com/omss-spec/template) **OMSS SDK:** [github.com/omss-spec/sdk](https://github.com/omss-spec/sdk) version: 1.1.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: http://localhost:{port} description: Development server (localhost only) variables: port: default: '3000' description: Port - url: https://{domain} description: Production server variables: domain: default: api.example.com description: Your hosted OMSS server security: [] tags: - name: Home description: General backend information and capabilities - name: Movies description: Movie streaming sources - name: TV description: TV episode streaming sources - name: Refresh description: Refresh cached source responses paths: /v1/movies/{id}: get: tags: - Movies summary: Movie sources description: Retrieve movie streaming sources by TMDB movie ID. operationId: getMovieSources parameters: - $ref: '#/components/parameters/MovieId' - $ref: '#/components/parameters/Platform' - $ref: '#/components/parameters/Provider' - $ref: '#/components/parameters/Filter' responses: '200': description: Movie sources and subtitles successfully retrieved. content: application/json: schema: $ref: '#/components/schemas/SourcesResponse' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '406': $ref: '#/components/responses/NotAcceptable' '415': $ref: '#/components/responses/UnsupportedMediaType' '500': $ref: '#/components/responses/InternalError' components: parameters: MovieId: name: id in: path required: true description: TMDB movie ID, numeric characters only, treated as a string. schema: type: string pattern: ^[0-9]+$ maxLength: 20 Platform: name: platform in: query required: false description: > Target platform for source optimization. For "web" the url fields must be directly usable in browsers without additional headers or CORS handling. For "native" the url fields are upstream URLs and headers are returned to be used by native players. Default is "web". schema: type: string enum: - web - native Provider: name: provider in: query required: false description: > Specific provider ID to fetch sources from. The response structure remains the same but only sources from this provider are returned. If the provider is unknown, a PROVIDER_NOT_FOUND error is returned. schema: type: string Filter: name: filter in: query required: false description: > Filter expression applied to the sources array (not subtitles) after retrieval and before the response is returned. Syntax: "condition[;condition...]" where ";" acts as logical AND. Supported operators: "==", "!=", "=in=", "=out=". The wildcard "*" MAY be used in values. Backends MUST support filtering on quality, type, streamable, provider.id, provider.name, audioTracks, and format. schema: type: string schemas: SourcesResponse: type: object description: > Success response for movie and TV episode endpoints, containing sources, subtitles, and diagnostics. required: - id - sources - subtitles - diagnostics properties: id: type: string format: uuid description: Unique response identifier (e.g. UUID v4). expiresAt: type: string format: date-time description: > Optional ISO 8601 timestamp when sources expire (for signed or temporary URLs). sources: type: array description: >- Array of streaming source objects. Must contain at least one element if any sources are available. items: $ref: '#/components/schemas/Source' subtitles: type: array description: Array of subtitle objects. May be empty. items: $ref: '#/components/schemas/Subtitle' diagnostics: type: array description: > Non-fatal warnings or errors about data quality, inference, or provider issues. May be empty. items: $ref: '#/components/schemas/Diagnostic' Source: type: object description: Streaming source with quality and technical metadata. required: - id - url - streamable - type - quality - audioTracks - provider properties: id: type: string format: uuid description: Unique source identifier (e.g. UUID v4). url: type: string format: uri description: > For platform=web: URL directly usable in HTML5 video players without CORS issues. For platform=native: upstream URL from the provider, possibly requiring CORS handling or custom headers (provided in headers). headers: type: object description: > Present only for platform=native. Key-value pairs of HTTP and non-standard HTTP headers to include when accessing the url. additionalProperties: type: string streamable: type: boolean description: > Indicates if the source is streamable (true) or a direct download link (false). Download links MUST NOT be used as streaming sources. type: type: string description: Source type. enum: - hls - mp4 - mkv - dash quality: type: string description: > Video quality. Should be inferred from resolution, bitrate, filename, or manifest information; use "Auto" when unknown. enum: - 8K - 4K - QHD - FHD - HD - SD - Auto audioTracks: type: array description: > Human-readable language names for available audio tracks. Use "Original" when the language cannot be determined. items: type: string provider: $ref: '#/components/schemas/ProviderRef' Subtitle: type: object description: Subtitle or caption track. required: - id - url - label - format - provider properties: id: type: string format: uuid description: Unique subtitle identifier (e.g. UUID v4). url: type: string format: uri description: > For platform=web: direct subtitle URL usable in HTML5 track elements without CORS issues. For platform=native: upstream subtitle URL from the provider, possibly requiring CORS handling or custom headers (provided in headers). headers: type: object description: > Present only for platform=native. Key-value pairs of HTTP and non-standard HTTP headers to include when accessing the url. additionalProperties: type: string label: type: string description: > Human-readable language name for the subtitle track. Use "Unknown" when the language cannot be determined. format: type: string description: Subtitle format. enum: - vtt - srt provider: $ref: '#/components/schemas/ProviderRef' Diagnostic: type: object description: Non-response-fatal warning or error encountered during scraping. required: - code - message - source - severity properties: code: type: string description: Machine-readable warning/error code. enum: - PROVIDER_ERROR - PARTIAL_SCRAPE message: type: string description: Human-readable description of the issue. source: type: string description: > Identifier of the source of the issue (e.g. provider ID). Empty string means the warning applies to the entire response. severity: type: string description: Warning/error severity. enum: - warning - error ErrorResponse: type: object description: Standard error response format for all non-2xx responses. required: - error - traceId properties: error: $ref: '#/components/schemas/ErrorObject' traceId: type: string description: Unique identifier for error tracking and debugging. ProviderRef: type: object description: Provider reference information included in sources and subtitles. required: - id - name properties: id: type: string description: Unique provider identifier. name: type: string description: Human-readable provider name. ErrorObject: type: object description: Error details container. 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 - PROVIDER_NOT_FOUND - RESPONSE_ID_NOT_FOUND - NO_SOURCES_AVAILABLE - ENDPOINT_NOT_FOUND - METHOD_NOT_ALLOWED - INTERNAL_ERROR - UNSUPPORTED_MEDIA_TYPE - NOT_ACCEPTABLE message: type: string description: Human-readable error description. details: description: > Optional additional context about the error. Frontends should not display this field directly. responses: BadRequest: description: > Bad request due to invalid or missing parameters, or invalid TMDB ID format. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' NotFound: description: > Resource not found, including media that does not exist for the given TMDB ID or media that exists but has no available sources. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' NotAcceptable: description: > The requested Accept header is not supported. OMSS supports JSON responses only. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' UnsupportedMediaType: description: Unsupported Content-Type in the request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' InternalError: description: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' ````