{"openapi":"3.1.0","info":{"title":"YTAPI","version":"1.0.0","description":"Transcript API for YouTube videos, plus video metadata, playlists, channels and search. Only HTTP 200 responses cost credits; errors are free. Errors use the envelope {\"error\": {\"code\", \"message\", \"retryable\"}}.","contact":{"name":"YTAPI support","url":"https://docs.ytapi.dev","email":"hello@ytapi.dev"}},"externalDocs":{"url":"https://docs.ytapi.dev"},"servers":[{"url":"https://api.ytapi.dev"}],"security":[{"BearerAuth":[]},{"ApiKeyHeader":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Your API key: Authorization: Bearer sk_..."},"ApiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Alternative to the Bearer header."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable code, e.g. captions_disabled, language_not_found, video_unavailable, region_blocked, rate_limited, insufficient_credits."},"message":{"type":"string"},"retryable":{"type":"boolean","description":"True when the same request may succeed if sent again later."}}}}},"Word":{"type":"object","properties":{"word":{"type":"string"},"start":{"type":"number","description":"Seconds"},"end":{"type":"number","description":"Seconds"}}},"Segment":{"type":"object","required":["text","start","end"],"properties":{"text":{"type":"string"},"start":{"type":"number","description":"Seconds"},"end":{"type":"number","description":"Seconds"},"duration":{"type":"number","description":"Seconds"},"words":{"type":"array","items":{"$ref":"#/components/schemas/Word"},"description":"Present with word_level=true on auto-generated tracks only."}}},"Transcript":{"type":"object","required":["video_id","language","segments"],"properties":{"video_id":{"type":"string"},"language":{"type":"string","description":"Language of the returned track, e.g. en. Check it when you asked for a fallback."},"track_kind":{"type":"string","enum":["manual","asr"],"description":"manual = creator captions, asr = auto-generated."},"duration_seconds":{"type":"number"},"has_word_level":{"type":"boolean"},"segments":{"type":"array","items":{"$ref":"#/components/schemas/Segment"}}}}},"responses":{"BadRequest":{"description":"Invalid parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"PaymentRequired":{"description":"Credit balance is empty (insufficient_credits).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"Access to the video is restricted, for example region_blocked. Free.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Not found: no captions (captions_disabled), no track in the requested language (language_not_found), or the video or resource is unavailable (video_unavailable). Free.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Over the key's rate limit. Wait for Retry-After seconds, then retry. Free.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests per second allowed for this key.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ServerError":{"description":"Temporary server or upstream failure. Free; safe to retry once when retryable is true.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/transcripts":{"post":{"operationId":"getTranscript","summary":"Get a video's transcript","description":"Returns the captions of a public YouTube video. Defaults: format=segments, languages=[\"*\"] (the video's own language, the one spoken in it), track_policy=manual_first. 1 credit.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["video_id"],"properties":{"video_id":{"type":"string","description":"11-character YouTube video ID.","example":"dQw4w9WgXcQ"},"format":{"type":"string","default":"segments","enum":["segments","word_timestamps","sentences","markdown","text","srt","vtt","json3"],"description":"markdown, text, srt and vtt return the document itself instead of JSON: markdown as text/markdown, text and srt as text/plain, vtt as text/vtt."},"word_level":{"type":"boolean","default":false,"description":"Include per-word timings. Only auto-generated tracks have them."},"languages":{"type":"array","items":{"type":"string"},"default":["*"],"description":"Language codes in order of preference. \"*\" is the video's own language, the one spoken in it. Pass [\"en\", \"*\"] for English when the video has it.","example":["es","*"]},"track_policy":{"type":"string","description":"Which track to take within a matched language. manual_first: creator captions, else auto-generated. asr_first: auto-generated, else creator captions (only auto-generated tracks have word timings). exact_only: only an exact language code (en does not match en-GB), creator captions first. Languages are tried in order before track kind. GET /v1/videos/{id}/basic-info lists each track's kind for free.","enum":["manual_first","asr_first","exact_only"],"default":"manual_first"}}}}}},"responses":{"200":{"description":"The transcript. JSON for segments, word_timestamps, sentences and json3; the raw document for markdown, text, srt and vtt.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Transcript"}},"text/markdown":{"schema":{"type":"string"}},"text/plain":{"schema":{"type":"string"}},"text/vtt":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}},"get":{"operationId":"getTranscriptByQuery","summary":"Get a video's transcript (query parameters)","description":"The same as POST /v1/transcripts, with the options as query parameters. 1 credit.","parameters":[{"name":"video_id","in":"query","required":true,"description":"11-character YouTube video ID.","schema":{"type":"string","example":"dQw4w9WgXcQ"}},{"name":"format","in":"query","description":"Output format; see POST /v1/transcripts. Default segments.","schema":{"type":"string","default":"segments","enum":["segments","word_timestamps","sentences","markdown","text","srt","vtt","json3"]}},{"name":"word_level","in":"query","description":"Include per-word timings.","schema":{"type":"boolean","default":false}},{"name":"languages","in":"query","description":"Comma-separated language codes in order of preference, e.g. \"es,*\". \"*\" is the video's own language. Default \"*\".","schema":{"type":"string"}},{"name":"track_policy","in":"query","description":"Which track to take within a matched language. manual_first: creator captions, else auto-generated. asr_first: auto-generated, else creator captions (only auto-generated tracks have word timings). exact_only: only an exact language code (en does not match en-GB), creator captions first. Languages are tried in order before track kind. GET /v1/videos/{id}/basic-info lists each track's kind for free.","schema":{"type":"string","enum":["manual_first","asr_first","exact_only"],"default":"manual_first"}}],"responses":{"200":{"description":"The transcript, as for POST /v1/transcripts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Transcript"}},"text/markdown":{"schema":{"type":"string"}},"text/plain":{"schema":{"type":"string"}},"text/vtt":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/v1/videos/{id}/basic-info":{"get":{"operationId":"getVideoBasicInfo","summary":"Get basic video info","description":"Title, duration, channel and available caption languages. Free (0 credits).","parameters":[{"name":"id","in":"path","required":true,"description":"YouTube video ID.","schema":{"type":"string"}}],"responses":{"200":{"description":"Basic video info.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/v1/videos/{id}/video-info":{"get":{"operationId":"getVideoInfo","summary":"Get full video info","description":"Full metadata: description, statistics, thumbnails, chapters and more. 1 credit.","parameters":[{"name":"id","in":"path","required":true,"description":"YouTube video ID.","schema":{"type":"string"}}],"responses":{"200":{"description":"Full video info.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/v1/playlists/{id}":{"get":{"operationId":"getPlaylist","summary":"Get a playlist","description":"Playlist details and its videos, one page at a time. Pass next_cursor as cursor for the next page; later pages carry videos only. 1 credit per page.","parameters":[{"name":"id","in":"path","required":true,"description":"Playlist ID (PL...) or playlist URL.","schema":{"type":"string"}},{"name":"cursor","in":"query","description":"Opaque continuation token from the previous page's response. Omit for the first page.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of the playlist's videos (with details on the first page) and the next cursor.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/v1/channels/{id}":{"get":{"operationId":"getChannel","summary":"Get a channel","description":"Title, handle, subscriber count, avatar, banner, verified status and links. 1 credit.","parameters":[{"name":"id","in":"path","required":true,"description":"Channel handle (e.g. @MrBeast) or channel ID (UC...).","schema":{"type":"string"}}],"responses":{"200":{"description":"Channel profile.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/v1/channels/{id}/latest":{"get":{"operationId":"listChannelLatestVideos","summary":"List a channel's latest videos","description":"The channel's most recent uploads. 1 credit.","parameters":[{"name":"id","in":"path","required":true,"description":"Channel handle or channel ID.","schema":{"type":"string"}}],"responses":{"200":{"description":"Latest videos.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/v1/channels/{id}/videos":{"get":{"operationId":"listChannelVideos","summary":"List a channel's videos","description":"A page of the channel's uploads, sorted as requested. 1 credit per page.","parameters":[{"name":"id","in":"path","required":true,"description":"Channel handle or channel ID.","schema":{"type":"string"}},{"name":"cursor","in":"query","description":"Opaque continuation token from the previous page's response. Omit for the first page.","schema":{"type":"string"}},{"name":"sort_by","in":"query","description":"Sort order.","schema":{"type":"string","enum":["newest","popular","oldest"],"default":"newest"}}],"responses":{"200":{"description":"A page of videos and the next cursor.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/v1/channels/{id}/playlists":{"get":{"operationId":"listChannelPlaylists","summary":"List a channel's playlists","description":"One page of the channel's playlists. 1 credit per page.","parameters":[{"name":"id","in":"path","required":true,"description":"Channel handle or channel ID.","schema":{"type":"string"}},{"name":"cursor","in":"query","description":"Opaque continuation token from the previous page's response. Omit for the first page.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of playlists and the next cursor.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/v1/search":{"get":{"operationId":"searchYouTube","summary":"Search YouTube","description":"Videos, channels, playlists, movies or Shorts matching a query, one page at a time. Pass next_cursor as cursor for the next page. 1 credit per page.","parameters":[{"name":"q","in":"query","required":true,"description":"Search query.","schema":{"type":"string"}},{"name":"type","in":"query","description":"Result type.","schema":{"type":"string","enum":["video","channel","playlist","movie","shorts"],"default":"video"}},{"name":"upload_date","in":"query","description":"Only results uploaded within this window.","schema":{"type":"string","enum":["hour","today","week","month","year"]}},{"name":"duration","in":"query","description":"short (under 4 minutes), medium (4 to 20) or long (over 20).","schema":{"type":"string","enum":["short","medium","long"]}},{"name":"sort_by","in":"query","schema":{"type":"string","enum":["relevance","rating","upload_date","view_count"],"default":"relevance"}},{"name":"limit","in":"query","description":"Maximum number of results.","schema":{"type":"integer","default":20}},{"name":"cursor","in":"query","description":"Opaque continuation token from the previous page's response. Omit for the first page.","schema":{"type":"string"}}],"responses":{"200":{"description":"Search results.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/v1/search/suggestions":{"get":{"operationId":"getSearchSuggestions","summary":"Get search suggestions","description":"Autocomplete suggestions for a partial query. Free.","parameters":[{"name":"q","in":"query","required":true,"description":"Partial query.","schema":{"type":"string"}},{"name":"hl","in":"query","description":"Interface language for the suggestions, e.g. \"es\".","schema":{"type":"string"}},{"name":"gl","in":"query","description":"Country whose searches the suggestions reflect, e.g. \"MX\".","schema":{"type":"string"}}],"responses":{"200":{"description":"Suggestions.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/v1/batch":{"post":{"operationId":"createBatchJob","summary":"Start a batch job","description":"Runs up to 100 transcript or basic_info tasks concurrently. Poll GET /v1/batch/{id} for results. 1 credit per successful task.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tasks"],"properties":{"concurrency":{"type":"integer","minimum":1,"maximum":20,"default":10,"description":"How many tasks run at the same time."},"tasks":{"type":"array","maxItems":100,"items":{"type":"object","required":["type","video_id"],"properties":{"id":{"type":"string","description":"Your own task ID, echoed in results."},"type":{"type":"string","enum":["transcript","basic_info"]},"video_id":{"type":"string"},"format":{"type":"string"}}}}}}}}},"responses":{"202":{"description":"Accepted. The job's id, status, task count and estimated credits.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/v1/batch/{id}":{"get":{"operationId":"getBatchJob","summary":"Get a batch job","description":"Status and per-task results of a batch job. Free.","parameters":[{"name":"id","in":"path","required":true,"description":"Batch job ID.","schema":{"type":"string"}}],"responses":{"200":{"description":"Job status and results.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}}}}