{"openapi":"3.1.0","info":{"title":"YouTube Transcript Developer API","description":"Developer API for turning YouTube videos, channels, and playlists into agent-ready transcript context.","version":"1.0.0"},"paths":{"/api/v1/":{"get":{"tags":["Developer API"],"summary":"API Health Check","description":"Health check for the Developer API.","operationId":"api_root_api_v1__get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/account/credits":{"get":{"tags":["Developer API"],"summary":"Get Credits","description":"Get your current credit balance.\n\nCredits are shared between API access and web dashboard.","operationId":"get_credits_api_v1_account_credits_get","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/transcripts/single":{"post":{"tags":["Developer API"],"summary":"Single Video Transcript","description":"Get transcript for a single YouTube video.\n\n**Cost:** 1 credit per video, refunded when no transcript is returned.\n\nServed from the shared transcript cache when possible. If YouTube is slow\nthe call returns 504 after about 45 s; the fetch keeps running and fills the\ncache, so retrying a minute later is usually instant.","operationId":"get_single_transcript_api_v1_transcripts_single_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleTranscriptRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleTranscriptResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/channels/{channel}/info":{"get":{"tags":["Developer API"],"summary":"Get Channel Info","description":"Get information about a YouTube channel.\n\n**Cost:** Free (no credits)\n\nUse this to validate a channel before starting a batch download.","operationId":"get_channel_info_api_v1_channels__channel__info_get","parameters":[{"name":"channel","in":"path","required":true,"schema":{"type":"string","title":"Channel"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelInfoResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/channels/{channel}/videos":{"get":{"tags":["Developer API"],"summary":"List Channel Videos","description":"List videos from a YouTube channel, up to `limit` (default 100, max 2000).\n\n**Cost:** Free (no credits)\n\nOrder: long-form videos, then Shorts, then past livestreams, each newest\nfirst. This is the order channel jobs use, so `limit=N` previews exactly\nwhat a job with `max_videos=N` downloads. `has_more` is true when the\nchannel has more videos than `limit`.","operationId":"list_channel_videos_api_v1_channels__channel__videos_get","parameters":[{"name":"channel","in":"path","required":true,"schema":{"type":"string","title":"Channel"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":2000,"minimum":1,"default":100,"title":"Limit"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelVideosResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/transcripts/channel":{"post":{"tags":["Developer API"],"summary":"Download Channel Transcripts","description":"Start downloading all transcripts from a YouTube channel.\n\n**Cost:** 1 credit per video\n\nThis is an asynchronous operation. Use the returned `job_id` to:\n- Check progress: `GET /api/v1/jobs/{job_id}`\n- Download results: `GET /api/v1/jobs/{job_id}/download`\n\nThe request returns quickly with a job_id. Discovery and credit reservation\ncontinue in the background; poll /api/v1/jobs/{job_id} for progress.","operationId":"download_channel_transcripts_api_v1_transcripts_channel_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelTranscriptRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/transcripts/playlist":{"post":{"tags":["Developer API"],"summary":"Download Playlist Transcripts","description":"Start downloading all transcripts from a YouTube playlist.\n\n**Cost:** 1 credit per video\n\nThis is an asynchronous operation. Use the returned `job_id` to check progress\nand download results when complete.","operationId":"download_playlist_transcripts_api_v1_transcripts_playlist_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlaylistTranscriptRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/jobs/{job_id}":{"get":{"tags":["Developer API"],"summary":"Get Job Status","description":"Get the status of a transcript download job.\n\nPoll this endpoint to track progress. When `download_ready` is true,\nuse the `download_url` to retrieve results.","operationId":"get_job_status_api_v1_jobs__job_id__get","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobStatusResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/jobs/{job_id}/cancel":{"post":{"tags":["Developer API"],"summary":"Cancel Job","description":"Cancel an owned job, refund unprocessed videos, and retain partial results.","operationId":"cancel_job_api_v1_jobs__job_id__cancel_post","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobCancellationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/jobs/{job_id}/download":{"get":{"tags":["Developer API"],"summary":"Download Job Results","description":"Download the transcript results for a completed job.\n\nReturns a ZIP file containing all transcripts.\nOnly available when job status is 'completed' or 'completed_with_errors'.\n`format` (txt, srt, vtt, json) picks the file format. Non-txt formats are one\nfile per video and ignore concatenate_all; videos from jobs created before\nsegment storage existed are returned as txt.\nOptional `include_timestamps`, `include_video_title`, `include_video_id`,\n`include_video_url`, `include_view_count`, and `concatenate_all` override the\njob's saved options for this download (older jobs keep their stored text).","operationId":"download_job_results_api_v1_jobs__job_id__download_get","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}},{"name":"format","in":"query","required":false,"schema":{"enum":["txt","srt","vtt","json"],"type":"string","default":"txt","title":"Format"}},{"name":"include_timestamps","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Override the job's timestamp setting for this download","title":"Include Timestamps"},"description":"Override the job's timestamp setting for this download"},{"name":"include_video_title","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Override the job's 'Video Title:' header setting","title":"Include Video Title"},"description":"Override the job's 'Video Title:' header setting"},{"name":"include_video_id","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Override the job's 'Video ID:' header setting","title":"Include Video Id"},"description":"Override the job's 'Video ID:' header setting"},{"name":"include_video_url","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Override the job's 'URL:' header setting","title":"Include Video Url"},"description":"Override the job's 'URL:' header setting"},{"name":"include_view_count","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Override the job's 'View Count:' header setting","title":"Include View Count"},"description":"Override the job's 'View Count:' header setting"},{"name":"concatenate_all","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Override the job's single-file setting (txt only)","title":"Concatenate All"},"description":"Override the job's single-file setting (txt only)"},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/jobs":{"get":{"tags":["Developer API"],"summary":"List Jobs","description":"List your recent transcript download jobs.\n\nOptionally filter by status: 'processing', 'completed', 'failed', etc.","operationId":"list_jobs_api_v1_jobs_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20,"title":"Limit"}},{"name":"status_filter","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status Filter"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"ChannelInfoResponse":{"properties":{"channel_id":{"type":"string","title":"Channel Id"},"title":{"type":"string","title":"Title"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"subscriber_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Subscriber Count"},"video_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Video Count"},"thumbnail_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Thumbnail Url"}},"type":"object","required":["channel_id","title","description","subscriber_count","video_count","thumbnail_url"],"title":"ChannelInfoResponse","description":"Response with channel information."},"ChannelTranscriptRequest":{"properties":{"channel":{"type":"string","title":"Channel","description":"YouTube channel name, handle (@channel), or channel ID","examples":["@mkbhd","MKBHD","UCBcRF18a7Qf58cCRy5xuWwQ"]},"max_videos":{"anyOf":[{"type":"integer","maximum":2000.0,"minimum":1.0},{"type":"null"}],"title":"Max Videos","description":"Maximum number of videos to process. None = all videos."},"options":{"$ref":"#/components/schemas/TranscriptOptions","description":"Transcript formatting options"}},"type":"object","required":["channel"],"title":"ChannelTranscriptRequest","description":"Request to download all transcripts from a channel."},"ChannelVideosResponse":{"properties":{"channel_id":{"type":"string","title":"Channel Id"},"channel_name":{"type":"string","title":"Channel Name"},"total_videos":{"type":"integer","title":"Total Videos"},"videos":{"items":{"$ref":"#/components/schemas/VideoInfo"},"type":"array","title":"Videos"},"duration_breakdown":{"additionalProperties":{"type":"integer"},"type":"object","title":"Duration Breakdown"},"limit":{"type":"integer","title":"Limit"},"has_more":{"type":"boolean","title":"Has More"}},"type":"object","required":["channel_id","channel_name","total_videos","videos","duration_breakdown","limit","has_more"],"title":"ChannelVideosResponse","description":"Response with channel videos list."},"CreditsResponse":{"properties":{"credits":{"type":"integer","title":"Credits"},"api_key_name":{"type":"string","title":"Api Key Name"},"total_api_requests":{"type":"integer","title":"Total Api Requests"},"total_credits_via_api":{"type":"integer","title":"Total Credits Via Api"}},"type":"object","required":["credits","api_key_name","total_api_requests","total_credits_via_api"],"title":"CreditsResponse","description":"Response with user's credit balance."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"JobCancellationResponse":{"properties":{"job_id":{"type":"string","title":"Job Id"},"status":{"type":"string","title":"Status"},"total_videos":{"type":"integer","title":"Total Videos"},"processed_count":{"type":"integer","title":"Processed Count"},"completed":{"type":"integer","title":"Completed"},"failed_count":{"type":"integer","title":"Failed Count"},"skipped_count":{"type":"integer","title":"Skipped Count"},"credits_used":{"type":"integer","title":"Credits Used"},"refunded_credits":{"type":"integer","title":"Refunded Credits"},"refunded_now":{"type":"integer","title":"Refunded Now"},"download_ready":{"type":"boolean","title":"Download Ready"},"download_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Download Url"}},"type":"object","required":["job_id","status","total_videos","processed_count","completed","failed_count","skipped_count","credits_used","refunded_credits","refunded_now","download_ready"],"title":"JobCancellationResponse"},"JobResponse":{"properties":{"job_id":{"type":"string","title":"Job Id"},"status":{"type":"string","title":"Status"},"total_videos":{"type":"integer","title":"Total Videos"},"source_type":{"type":"string","title":"Source Type"},"source_name":{"type":"string","title":"Source Name"},"credits_reserved":{"type":"integer","title":"Credits Reserved"},"message":{"type":"string","title":"Message"}},"type":"object","required":["job_id","status","total_videos","source_type","source_name","credits_reserved","message"],"title":"JobResponse","description":"Response when a job is created."},"JobStatusResponse":{"properties":{"job_id":{"type":"string","title":"Job Id"},"status":{"type":"string","title":"Status"},"total_videos":{"type":"integer","title":"Total Videos"},"processed_count":{"type":"integer","title":"Processed Count"},"completed":{"type":"integer","title":"Completed"},"failed_count":{"type":"integer","title":"Failed Count"},"skipped_count":{"type":"integer","title":"Skipped Count","default":0},"credits_used":{"type":"integer","title":"Credits Used"},"refunded_credits":{"type":"integer","title":"Refunded Credits","default":0},"source_type":{"type":"string","title":"Source Type"},"source_name":{"type":"string","title":"Source Name"},"download_ready":{"type":"boolean","title":"Download Ready"},"download_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Download Url"},"elapsed_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Elapsed Seconds"},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message"}},"type":"object","required":["job_id","status","total_videos","processed_count","completed","failed_count","credits_used","source_type","source_name","download_ready"],"title":"JobStatusResponse","description":"Response with job status and progress."},"PlaylistTranscriptRequest":{"properties":{"playlist":{"type":"string","title":"Playlist","description":"YouTube playlist ID or URL","examples":["PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf"]},"max_videos":{"anyOf":[{"type":"integer","maximum":2000.0,"minimum":1.0},{"type":"null"}],"title":"Max Videos","description":"Maximum number of videos to process. None = all videos."},"options":{"$ref":"#/components/schemas/TranscriptOptions","description":"Transcript formatting options"}},"type":"object","required":["playlist"],"title":"PlaylistTranscriptRequest","description":"Request to download all transcripts from a playlist."},"SingleTranscriptRequest":{"properties":{"video_url":{"type":"string","title":"Video Url","description":"YouTube video URL or video ID (e.g., 'dQw4w9WgXcQ')"},"include_timestamps":{"type":"boolean","title":"Include Timestamps","description":"Include timestamps in transcript","default":false}},"type":"object","required":["video_url"],"title":"SingleTranscriptRequest","description":"Request to download a single video transcript."},"SingleTranscriptResponse":{"properties":{"video_id":{"type":"string","title":"Video Id"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"transcript":{"type":"string","title":"Transcript"},"language":{"type":"string","title":"Language"},"character_count":{"type":"integer","title":"Character Count"},"credits_used":{"type":"integer","title":"Credits Used","default":1}},"type":"object","required":["video_id","transcript","language","character_count"],"title":"SingleTranscriptResponse","description":"Response with single video transcript."},"TranscriptOptions":{"properties":{"include_timestamps":{"type":"boolean","title":"Include Timestamps","description":"Include [MM:SS] timestamps in transcript text","default":false},"include_video_title":{"type":"boolean","title":"Include Video Title","description":"Include video title in transcript header","default":true},"include_video_id":{"type":"boolean","title":"Include Video Id","description":"Include video ID in transcript header","default":true},"include_video_url":{"type":"boolean","title":"Include Video Url","description":"Include video URL in transcript header","default":true},"include_view_count":{"type":"boolean","title":"Include View Count","description":"Include view count in transcript header","default":false},"concatenate_all":{"type":"boolean","title":"Concatenate All","description":"Return all transcripts in a single file instead of individual files","default":false}},"type":"object","title":"TranscriptOptions","description":"Common formatting options for transcripts."},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"VideoInfo":{"properties":{"id":{"type":"string","title":"Id"},"title":{"type":"string","title":"Title"},"url":{"type":"string","title":"Url"},"duration_seconds":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Duration Seconds"},"duration_category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Duration Category"},"view_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"View Count"},"published_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Published At"},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Type"}},"type":"object","required":["id","title","url","duration_seconds","duration_category","view_count","published_at"],"title":"VideoInfo","description":"Video metadata."}}}}