{"openapi":"3.1.0","info":{"title":"VideoResolver API","version":"0.0.1","description":"Download public videos and audio from a link. Authenticate with a personal API key from your account (Bearer token). Downloads cost 1 credit per started minute of media. Failed downloads are refunded. The same key works with the MCP server at /api/mcp."},"externalDocs":{"description":"Documentation","url":"https://www.videoresolver.com/docs"},"servers":[{"url":"https://www.videoresolver.com/api/v1"}],"security":[{"bearerAuth":[]}],"paths":{"/account":{"get":{"operationId":"getAccount","summary":"Plan and remaining credits","description":"Your plan and the credits left, monthly allowance and packs included.","responses":{"200":{"description":"Account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"},"example":{"plan":"basic","plan_name":"Basic","credits":987,"renews_at":"2026-12-01T09:12:44.000Z","manage_url":"https://www.videoresolver.com/app"}}}},"401":{"description":"unauthorized: The API key is missing, revoked or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: More than 60 lookups in an hour, or too many at once. Retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"generic: Unexpected error on our side. Retry in a moment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/media":{"get":{"operationId":"getMedia","summary":"Look up a link","description":"Title, duration and the credits a download would cost. Nothing is downloaded or charged.","parameters":[{"name":"url","in":"query","required":true,"description":"Public link to the video or audio","schema":{"type":"string","format":"uri"},"example":"https://www.youtube.com/watch?v=jNQXAC9IVRw"}],"responses":{"200":{"description":"Media details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Media"},"example":{"title":"Me at the zoo","channel":"jawed","platform":"Youtube","thumbnail":"https://i.ytimg.com/vi/jNQXAC9IVRw/hqdefault.jpg?sqp=…","duration_seconds":19,"credits_required":1}}}},"400":{"description":"invalid_url: The url is missing or isn't an http(s) link.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized: The API key is missing, revoked or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"unreadable_video: The media is private, deleted, age-restricted or from an unsupported site. unsupported_live: Live streams and media without a duration can't be downloaded. unreadable_video: The media couldn't be read right now. Retry in a moment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: More than 60 lookups in an hour, or too many at once. Retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"generic: Unexpected error on our side. Retry in a moment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"unreadable_video: The media is private, deleted, age-restricted or from an unsupported site. unreadable_video: The media couldn't be read right now. Retry in a moment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/downloads":{"post":{"operationId":"createDownload","summary":"Start a download","description":"Looks up the link and starts the download. Downloads cost 1 credit per started minute of media. Nothing is charged when the balance doesn't cover the media (402), and a failed download is refunded. Then poll GET /downloads/{id} until status is ready.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"Public link to the video or audio"},"format":{"type":"string","enum":["mp4","mp3","m4a","wav"],"default":"mp4","description":"mp4 for video, mp3, m4a or wav for audio only. Anything other than mp4 at best quality needs a paid plan or credits from a pack."},"quality":{"type":"string","enum":["best","1080p","720p","480p","360p","320kbps","128kbps"],"default":"best","description":"Depends on the format: mp4: best, 1080p, 720p, 480p, 360p; mp3: best, 320kbps, 128kbps; m4a: best, 320kbps, 128kbps; wav: best."}}},"example":{"url":"https://www.youtube.com/watch?v=jNQXAC9IVRw","format":"mp4"}}}},"responses":{"202":{"description":"Download started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Download"},"example":{"download_id":"162b76ab-833e-4720-b687-dac284d479aa","title":"Me at the zoo","channel":"jawed","platform":"Youtube","thumbnail":"https://i.ytimg.com/vi/jNQXAC9IVRw/hqdefault.jpg?sqp=…","duration_seconds":19,"format":"mp4","quality":"best","status":"processing","progress":0,"credits":1,"size_bytes":null,"created_at":"2026-11-02T10:30:31.120Z","expires_at":null}}}},"400":{"description":"invalid_url: The url is missing or isn't an http(s) link. invalid_option: The format or quality isn't supported. Qualities depend on the format (mp4: best, 1080p, 720p, 480p, 360p; mp3: best, 320kbps, 128kbps; m4a: best, 320kbps, 128kbps; wav: best).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized: The API key is missing, revoked or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits: The balance doesn't cover the media. The message says how many credits are missing; nothing is charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"insufficient_credits","message":"Not enough credits. Choose a plan or a credit pack in your account. 1 more credit needed."}}}}},"403":{"description":"paid_option: Anything other than mp4 at best quality needs a paid plan or credits from a pack.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"unreadable_video: The media is private, deleted, age-restricted or from an unsupported site. unsupported_live: Live streams and media without a duration can't be downloaded. unreadable_video: The media couldn't be read right now. Retry in a moment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: More than 60 lookups in an hour, or too many at once. Retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"generic: Unexpected error on our side. Retry in a moment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"unreadable_video: The media is private, deleted, age-restricted or from an unsupported site. unreadable_video: The media couldn't be read right now. Retry in a moment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"listDownloads","summary":"List downloads","description":"Your most recent downloads, newest first.","parameters":[{"name":"limit","in":"query","description":"How many downloads to return","schema":{"type":"integer","minimum":1,"maximum":50,"default":20},"example":"5"}],"responses":{"200":{"description":"Downloads","content":{"application/json":{"schema":{"type":"object","required":["downloads"],"properties":{"downloads":{"type":"array","items":{"$ref":"#/components/schemas/Download"}}}},"example":{"downloads":[{"download_id":"162b76ab-833e-4720-b687-dac284d479aa","title":"Me at the zoo","channel":"jawed","platform":"Youtube","thumbnail":"https://i.ytimg.com/vi/jNQXAC9IVRw/hqdefault.jpg?sqp=…","duration_seconds":19,"format":"mp4","quality":"best","status":"ready","progress":100,"credits":1,"size_bytes":475989,"created_at":"2026-11-02T10:30:31.120Z","expires_at":"2026-11-04T10:30:46.678Z","download_url":"https://www.videoresolver.com/api/downloads/162b76ab-833e-4720-b687-dac284d479aa?token=…"}]}}}},"401":{"description":"unauthorized: The API key is missing, revoked or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: More than 60 lookups in an hour, or too many at once. Retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"generic: Unexpected error on our side. Retry in a moment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/downloads/{id}":{"get":{"operationId":"getDownload","summary":"Get a download","description":"Status and progress. Once status is ready, download_url is a signed link valid for 1 hour: call again for a fresh one while the file is kept (48 hours). Progress is refreshed about every 15 seconds, so polling every 5 to 10 seconds is plenty.","parameters":[{"name":"id","in":"path","required":true,"description":"download_id returned when the download started","schema":{"type":"string","format":"uuid"},"example":"162b76ab-833e-4720-b687-dac284d479aa"}],"responses":{"200":{"description":"Download","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Download"},"example":{"download_id":"162b76ab-833e-4720-b687-dac284d479aa","title":"Me at the zoo","channel":"jawed","platform":"Youtube","thumbnail":"https://i.ytimg.com/vi/jNQXAC9IVRw/hqdefault.jpg?sqp=…","duration_seconds":19,"format":"mp4","quality":"best","status":"ready","progress":100,"credits":1,"size_bytes":475989,"created_at":"2026-11-02T10:30:31.120Z","expires_at":"2026-11-04T10:30:46.678Z","download_url":"https://www.videoresolver.com/api/downloads/162b76ab-833e-4720-b687-dac284d479aa?token=…"}}}},"401":{"description":"unauthorized: The API key is missing, revoked or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: No download with this id on your account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: More than 60 lookups in an hour, or too many at once. Retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"generic: Unexpected error on our side. Retry in a moment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Personal API key (vr_…), created in your account."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_url","invalid_option","unauthorized","insufficient_credits","paid_option","not_found","unreadable_video","unsupported_live","rate_limited","generic"],"description":"Stable code to branch on"},"message":{"type":"string","description":"Human-readable explanation"}}}}},"Account":{"type":"object","required":["plan","plan_name","credits","renews_at","manage_url"],"properties":{"plan":{"type":"string","enum":["free","basic","pro","mega"],"description":"Plan id"},"plan_name":{"type":"string","description":"Display name of the plan"},"credits":{"type":"integer","description":"Credits left, packs included"},"renews_at":{"type":["string","null"],"format":"date-time","description":"Next renewal of a paid plan"},"manage_url":{"type":"string","format":"uri","description":"Where to change plan or buy a pack"}}},"Media":{"type":"object","required":["title","duration_seconds","credits_required"],"properties":{"title":{"type":"string"},"channel":{"type":["string","null"],"description":"Author or channel"},"platform":{"type":["string","null"],"description":"Site the media comes from"},"thumbnail":{"type":["string","null"],"format":"uri"},"duration_seconds":{"type":"integer"},"credits_required":{"type":"integer","description":"What a download costs: 1 per started minute"}}},"Download":{"type":"object","required":["download_id","status","progress","format","quality","credits"],"properties":{"download_id":{"type":"string","format":"uuid"},"title":{"type":"string"},"channel":{"type":["string","null"]},"platform":{"type":["string","null"]},"thumbnail":{"type":["string","null"],"format":"uri"},"duration_seconds":{"type":"integer"},"format":{"type":"string","enum":["mp4","mp3","m4a","wav"]},"quality":{"type":"string","enum":["best","1080p","720p","480p","360p","320kbps","128kbps"]},"status":{"type":"string","enum":["analyzed","processing","storing","ready","failed","expired"],"description":"analyzed: Looked up but not started (e.g. after a 402). Not charged. processing: Charged and downloading; progress goes from 0 to 98. storing: Downloaded, being saved to private storage. ready: download_url is set: a signed link valid for 1 hour. failed: Couldn't be downloaded; the credits were refunded. expired: The file was deleted after 48 hours."},"progress":{"type":"integer","minimum":0,"maximum":100},"credits":{"type":"integer","description":"Credits this download costs"},"size_bytes":{"type":["integer","null"],"description":"File size, once ready"},"created_at":{"type":"string","format":"date-time"},"expires_at":{"type":["string","null"],"format":"date-time","description":"When the file is deleted, 48 hours after it's ready"},"download_url":{"type":"string","format":"uri","description":"Only when status is ready: signed link valid for 1 hour"}}}}}}