{"openapi":"3.1.0","info":{"title":"VSub API","version":"1.0.0","summary":"Subtitle aggregation and movie/TV metadata for developers.","description":"VSub is a public developer API that returns (a) aggregated subtitle metadata with direct download URLs and (b) movie/TV metadata sourced from open data.\n\nThe API returns **subtitles and metadata only**. It does not return, resolve, or proxy video streams; there is no `stream_url`, resolver, or `m3u8` field anywhere in this API.\n\nMetadata facts and id crosswalks default to **Wikidata (CC0)**. A richer metadata tier backed by TMDB is available only to keys provisioned under a licensed agreement; when TMDB-backed fields are returned, the attribution string \"This product uses the TMDB API but is not endorsed or certified by TMDB.\" applies.\n\nSee the legal pages: [Terms](/tos), [DMCA](/dmca), [Privacy](/privacy).","termsOfService":"https://api.vsub.dev/tos","contact":{"name":"VSub Support","url":"https://api.vsub.dev/docs","email":"support@vsub.dev"},"license":{"name":"API Terms of Service","url":"https://api.vsub.dev/tos"}},"servers":[{"url":"https://api.vsub.dev","description":"Production"}],"tags":[{"name":"Subtitles","description":"Aggregated subtitle search returning direct download URLs."},{"name":"Metadata","description":"Movie/TV facts. Wikidata (CC0) by default; TMDB only on licensed keys."},{"name":"Resolution","description":"Crosswalk between IMDb and TMDB identifiers."}],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"paths":{"/v1/subtitles":{"get":{"operationId":"searchSubtitles","tags":["Subtitles"],"summary":"Search subtitles","description":"Returns a flat array of subtitle entries for a title, each with a direct download `url`. Accepts either a TMDB id (numeric) or an IMDb id (leading `tt`) in the `id` parameter.\n\nThis endpoint returns subtitle metadata and download links only. It never returns a video stream URL.","parameters":[{"name":"id","in":"query","required":true,"description":"TMDB id (numeric, e.g. `603`) or IMDb id (e.g. `tt0133093`). IMDb ids are detected by the leading `tt`.","schema":{"type":"string","examples":["tt0133093","603"]}},{"name":"season","in":"query","required":false,"description":"Season number for TV titles.","schema":{"type":"integer","minimum":0}},{"name":"episode","in":"query","required":false,"description":"Episode number for TV titles.","schema":{"type":"integer","minimum":0}},{"name":"language","in":"query","required":false,"description":"Comma-separated ISO 639-1 language codes (e.g. `en,es`). Omit for all languages.","schema":{"type":"string","examples":["en","en,es,fr"]}},{"name":"format","in":"query","required":false,"description":"Desired subtitle format.","schema":{"type":"string","enum":["srt","vtt","ass","ssa","sub"]}},{"name":"encoding","in":"query","required":false,"description":"Desired text encoding for the returned files (e.g. `utf-8`).","schema":{"type":"string","examples":["utf-8"]}},{"name":"hi","in":"query","required":false,"description":"Filter for hearing-impaired subtitles. `true` only HI, `false` only non-HI, omit for both.","schema":{"type":"boolean"}},{"name":"source","in":"query","required":false,"description":"Restrict to a single aggregation source.","schema":{"type":"string","examples":["opensubtitles","subdl"]}}],"responses":{"200":{"description":"Matching subtitles.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Subtitle"}},"examples":{"matrix-en":{"summary":"English subtitles for The Matrix","value":[{"id":"9f86d081884c7d65","url":"https://api.vsub.dev/v1/subtitles/file/9f86d081884c7d65","language":"en","languageName":"English","format":"srt","encoding":"utf-8","release":"The.Matrix.1999.1080p.BluRay.x264","origin":"BLURAY","hearingImpaired":false,"ai":false,"source":"opensubtitles"}]}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/UpstreamError"},"503":{"$ref":"#/components/responses/UpstreamUnavailable"}}}},"/v1/metadata/{id}":{"get":{"operationId":"getMetadata","tags":["Metadata"],"summary":"Get title metadata","description":"Returns basic facts for a title. Default fields are sourced from Wikidata (CC0). TMDB-backed fields (artwork, rich descriptions) are returned only for keys provisioned under a licensed tier and carry the TMDB attribution requirement.\n\nThis endpoint returns descriptive metadata only — never a video stream URL.","parameters":[{"name":"id","in":"path","required":true,"description":"TMDB id (numeric) or IMDb id (`tt...`).","schema":{"type":"string","examples":["tt0133093","603"]}}],"responses":{"200":{"description":"Title metadata.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Metadata"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/UpstreamError"},"503":{"$ref":"#/components/responses/UpstreamUnavailable"}}}},"/v1/find":{"get":{"operationId":"findId","tags":["Resolution"],"summary":"Resolve an identifier","description":"Crosswalks an external identifier to the canonical id set. Given an IMDb id, returns the TMDB id (and vice versa) plus media type and basic title facts. Backed by the Wikidata (CC0) id graph.","parameters":[{"name":"id","in":"query","required":true,"description":"The identifier value to resolve (e.g. `tt0133093` or `603`).","schema":{"type":"string","examples":["tt0133093","603"]}},{"name":"source","in":"query","required":false,"description":"Which identifier space `id` belongs to. Auto-detected when omitted.","schema":{"type":"string","enum":["imdb_id","tmdb_id"]}}],"responses":{"200":{"description":"Resolved identifiers.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdResolution"},"examples":{"matrix":{"value":{"imdb_id":"tt0133093","tmdb_id":603,"media_type":"movie","title":"The Matrix","year":1999}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/UpstreamError"},"503":{"$ref":"#/components/responses/UpstreamUnavailable"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Pass your API key as `Authorization: Bearer <key>`."},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Alternatively, pass your API key in the `X-API-Key` header. Never put the key in a query string."}},"headers":{"X-RateLimit-Limit":{"description":"Requests permitted in the current window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix epoch seconds when the window resets.","schema":{"type":"integer"}}},"schemas":{"Subtitle":{"type":"object","description":"A single subtitle entry with a direct download URL. Contains no video stream reference of any kind.","required":["id","url","language","format","source"],"properties":{"id":{"type":"string","description":"Content-hash id of the normalized subtitle (also the download key)."},"url":{"type":"string","format":"uri","description":"Direct download URL for the subtitle file, served from this API's origin."},"language":{"type":"string","description":"ISO 639-1 language code."},"languageName":{"type":"string","description":"Human-readable language name."},"format":{"type":"string","enum":["srt","vtt","ass","ssa","sub"]},"encoding":{"type":"string","description":"Text encoding of the file."},"release":{"type":"string","description":"Release name the subtitle was timed against."},"origin":{"type":"string","description":"Source media class.","examples":["WEB","BLURAY","HDTV"]},"hearingImpaired":{"type":"boolean"},"ai":{"type":"boolean","description":"Whether the subtitle was machine-generated/translated."},"source":{"type":"string","description":"Aggregation source the entry came from."}}},"Metadata":{"type":"object","description":"Basic descriptive facts for a title. No stream URL is ever included.","required":["id","media_type","title"],"properties":{"id":{"type":"string","description":"Canonical id key, e.g. `tmdb:movie:603`."},"imdb_id":{"type":"string"},"tmdb_id":{"type":"integer"},"media_type":{"type":"string","enum":["movie","tv"]},"title":{"type":"string"},"original_title":{"type":"string"},"year":{"type":"integer"},"overview":{"type":"string"},"genres":{"type":"array","items":{"type":"string"}},"runtime":{"type":"integer","description":"Runtime in minutes, when known."},"source":{"type":"string","description":"Provenance of the facts.","enum":["wikidata","tmdb"]},"attribution":{"type":"string","description":"Required attribution string when `source` is `tmdb`."}}},"IdResolution":{"type":"object","required":["media_type"],"properties":{"imdb_id":{"type":"string"},"tmdb_id":{"type":"integer"},"media_type":{"type":"string","enum":["movie","tv"]},"title":{"type":"string"},"year":{"type":"integer"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable description."}}}}}},"responses":{"BadRequest":{"description":"The request was malformed (missing or invalid parameters).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"bad_request","message":"Parameter 'id' is required."}}}}},"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"A valid API key is required."}}}}},"NotFound":{"description":"No resource matched the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"No record found for the supplied id."}}}}},"RateLimited":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit exceeded. Retry after the window resets."}}}}},"UpstreamError":{"description":"A data source returned an unexpected response. No source detail is disclosed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"upstream_error","message":"An upstream data source returned an unexpected response."}}}}},"UpstreamUnavailable":{"description":"A required data source is temporarily unavailable. No source detail is disclosed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"upstream_unavailable","message":"A required data source is temporarily unavailable. Please retry shortly."}}}}}}}}