{"openapi":"3.1.0","info":{"title":"YouTubeSearch API","description":"Clean YouTube data for AI agents: search, transcripts, summaries.\n\nAuth: `Authorization: Bearer ys_live_...` required on every call — free tier: 1,000 credits/month, no card.\n\nCredits: search 1/query · video 1 · transcript 1 cached / 2 cold / 10 ASR · summary 1 cached / 5 cold. Responses include X-Credits-Charged and X-Credits-Remaining.","version":"0.1.0"},"paths":{"/v1/videos/{video_id}/transcript":{"get":{"summary":"Timestamped transcript","description":"Cache-first transcript. Credits: 1 cached, 2 cold fetch, 10 when the ASR fallback transcribes a caption-less video. Requires an API key — free, 1,000 credits/mo, no card.","operationId":"get_transcript_v1_videos__video_id__transcript_get","security":[{"BearerAuth":[]}],"parameters":[{"name":"video_id","in":"path","required":true,"schema":{"type":"string","title":"Video Id"}},{"name":"format","in":"query","required":false,"schema":{"enum":["markdown","json","plain"],"type":"string","default":"markdown","title":"Format"}},{"name":"start","in":"query","required":false,"schema":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"title":"Start"}},{"name":"end","in":"query","required":false,"schema":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"title":"End"}},{"name":"max_tokens","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"title":"Max Tokens"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranscriptResponse"}}},"headers":{"X-Server-Time-Ms":{"description":"API processing time in milliseconds.","schema":{"type":"integer"}},"X-Credits-Charged":{"description":"Credits charged for a successful keyed request.","schema":{"type":"integer"}},"X-Credits-Remaining":{"description":"Monthly credits remaining after a successful keyed request.","schema":{"type":"integer"}}}},"400":{"description":"The request is invalid. Fix it before retrying.","content":{"application/json":{"example":{"error":"INVALID_REQUEST","message":"The request parameters are invalid."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The key is missing, invalid, or has been revoked.","content":{"application/json":{"example":{"error":"KEY_REQUIRED","message":"An API key is required — get a free key (1,000 credits/month, no card) at https://youtubesearch.dev/login."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited or temporarily blocked. Honor Retry-After when present.","content":{"application/json":{"example":{"error":"RATE_LIMITED","message":"Rate limit exceeded."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"500":{"description":"Unexpected server failure. Retry with backoff.","content":{"application/json":{"example":{"error":"INTERNAL_ERROR","message":"Internal server error."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream provider failed. Retry with backoff.","content":{"application/json":{"example":{"error":"UPSTREAM_FAILED","message":"An upstream provider failed."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"A required backend is unavailable. Retry with backoff.","content":{"application/json":{"example":{"error":"SERVICE_UNAVAILABLE","message":"A required backend is unavailable."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The key has exhausted its monthly credits.","content":{"application/json":{"example":{"error":"OUT_OF_CREDITS","message":"Monthly credit allowance exhausted."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"YouTube has restricted access to the requested video.","content":{"application/json":{"example":{"error":"AGE_RESTRICTED","message":"This video is age restricted."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The video or requested resource is unavailable.","content":{"application/json":{"example":{"error":"VIDEO_UNAVAILABLE","message":"This video is unavailable."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/search":{"post":{"summary":"Search videos","description":"Query (or 1-5 queries) -> top videos with native metadata plus the cached executive summary when available. Credits: 1 per query. Requires an API key — free, 1,000 credits/mo, no card.","operationId":"search_endpoint_v1_search_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchBody"}}},"required":true},"responses":{"200":{"description":"Successful response.","headers":{"X-Server-Time-Ms":{"description":"API processing time in milliseconds.","schema":{"type":"integer"}},"X-Credits-Charged":{"description":"Credits charged for a successful keyed request.","schema":{"type":"integer"}},"X-Credits-Remaining":{"description":"Monthly credits remaining after a successful keyed request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/SearchSingleResponse"},{"$ref":"#/components/schemas/SearchBatchResponse"}],"title":"Response 200 Search Endpoint V1 Search Post"}}}},"400":{"description":"The request is invalid. Fix it before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"INVALID_REQUEST","message":"The request parameters are invalid."}}}},"401":{"description":"The key is missing, invalid, or has been revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"KEY_REQUIRED","message":"An API key is required — get a free key (1,000 credits/month, no card) at https://youtubesearch.dev/login."}}}},"429":{"description":"Rate limited or temporarily blocked. Honor Retry-After when present.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"RATE_LIMITED","message":"Rate limit exceeded."}}}},"500":{"description":"Unexpected server failure. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"INTERNAL_ERROR","message":"Internal server error."}}}},"502":{"description":"An upstream provider failed. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"UPSTREAM_FAILED","message":"An upstream provider failed."}}}},"503":{"description":"A required backend is unavailable. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"SERVICE_UNAVAILABLE","message":"A required backend is unavailable."}}}},"402":{"description":"The key has exhausted its monthly credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"OUT_OF_CREDITS","message":"Monthly credit allowance exhausted."}}}}},"security":[{"BearerAuth":[]}]}},"/v1/videos/{video_id}":{"get":{"summary":"Video metadata","description":"Native metadata + chapters, cache-first (7-day refresh). Credits: 1. Requires an API key — free, 1,000 credits/mo, no card.","operationId":"get_video_v1_videos__video_id__get","security":[{"BearerAuth":[]}],"parameters":[{"name":"video_id","in":"path","required":true,"schema":{"type":"string","title":"Video Id"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoResponse"}}},"headers":{"X-Server-Time-Ms":{"description":"API processing time in milliseconds.","schema":{"type":"integer"}},"X-Credits-Charged":{"description":"Credits charged for a successful keyed request.","schema":{"type":"integer"}},"X-Credits-Remaining":{"description":"Monthly credits remaining after a successful keyed request.","schema":{"type":"integer"}}}},"400":{"description":"The request is invalid. Fix it before retrying.","content":{"application/json":{"example":{"error":"INVALID_REQUEST","message":"The request parameters are invalid."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The key is missing, invalid, or has been revoked.","content":{"application/json":{"example":{"error":"KEY_REQUIRED","message":"An API key is required — get a free key (1,000 credits/month, no card) at https://youtubesearch.dev/login."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited or temporarily blocked. Honor Retry-After when present.","content":{"application/json":{"example":{"error":"RATE_LIMITED","message":"Rate limit exceeded."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"500":{"description":"Unexpected server failure. Retry with backoff.","content":{"application/json":{"example":{"error":"INTERNAL_ERROR","message":"Internal server error."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream provider failed. Retry with backoff.","content":{"application/json":{"example":{"error":"UPSTREAM_FAILED","message":"An upstream provider failed."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"A required backend is unavailable. Retry with backoff.","content":{"application/json":{"example":{"error":"SERVICE_UNAVAILABLE","message":"A required backend is unavailable."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The key has exhausted its monthly credits.","content":{"application/json":{"example":{"error":"OUT_OF_CREDITS","message":"Monthly credit allowance exhausted."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"YouTube has restricted access to the requested video.","content":{"application/json":{"example":{"error":"AGE_RESTRICTED","message":"This video is age restricted."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The video or requested resource is unavailable.","content":{"application/json":{"example":{"error":"VIDEO_UNAVAILABLE","message":"This video is unavailable."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/videos/{video_id}/summary":{"get":{"summary":"Video summary","description":"The fewest-tokens way to understand a video: one narrative summary. Skim summaries first, then pull the full transcript for the videos that matter. Credits: 1 cached, 5 cold (cold generation also queues an async premium upgrade). Requires an API key — free, 1,000 credits/mo, no card.","operationId":"get_summary_v1_videos__video_id__summary_get","security":[{"BearerAuth":[]}],"parameters":[{"name":"video_id","in":"path","required":true,"schema":{"type":"string","title":"Video Id"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SummaryResponse"}}},"headers":{"X-Server-Time-Ms":{"description":"API processing time in milliseconds.","schema":{"type":"integer"}},"X-Credits-Charged":{"description":"Credits charged for a successful keyed request.","schema":{"type":"integer"}},"X-Credits-Remaining":{"description":"Monthly credits remaining after a successful keyed request.","schema":{"type":"integer"}}}},"400":{"description":"The request is invalid. Fix it before retrying.","content":{"application/json":{"example":{"error":"INVALID_REQUEST","message":"The request parameters are invalid."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The key is missing, invalid, or has been revoked.","content":{"application/json":{"example":{"error":"KEY_REQUIRED","message":"An API key is required — get a free key (1,000 credits/month, no card) at https://youtubesearch.dev/login."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited or temporarily blocked. Honor Retry-After when present.","content":{"application/json":{"example":{"error":"RATE_LIMITED","message":"Rate limit exceeded."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"500":{"description":"Unexpected server failure. Retry with backoff.","content":{"application/json":{"example":{"error":"INTERNAL_ERROR","message":"Internal server error."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream provider failed. Retry with backoff.","content":{"application/json":{"example":{"error":"UPSTREAM_FAILED","message":"An upstream provider failed."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"A required backend is unavailable. Retry with backoff.","content":{"application/json":{"example":{"error":"SERVICE_UNAVAILABLE","message":"A required backend is unavailable."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The key has exhausted its monthly credits.","content":{"application/json":{"example":{"error":"OUT_OF_CREDITS","message":"Monthly credit allowance exhausted."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"YouTube has restricted access to the requested video.","content":{"application/json":{"example":{"error":"AGE_RESTRICTED","message":"This video is age restricted."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The video or requested resource is unavailable.","content":{"application/json":{"example":{"error":"VIDEO_UNAVAILABLE","message":"This video is unavailable."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/credits":{"get":{"summary":"Credit balance","description":"Current month's credit usage for your key. Free — costs 0 credits.","operationId":"get_credits_v1_credits_get","responses":{"200":{"description":"Successful response.","headers":{"X-Server-Time-Ms":{"description":"API processing time in milliseconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditsResponse"}}}},"400":{"description":"The request is invalid. Fix it before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"INVALID_REQUEST","message":"The request parameters are invalid."}}}},"401":{"description":"The key is missing, invalid, or has been revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"KEY_REQUIRED","message":"An API key is required — get a free key (1,000 credits/month, no card) at https://youtubesearch.dev/login."}}}},"429":{"description":"Rate limited or temporarily blocked. Honor Retry-After when present.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"RATE_LIMITED","message":"Rate limit exceeded."}}}},"500":{"description":"Unexpected server failure. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"INTERNAL_ERROR","message":"Internal server error."}}}},"502":{"description":"An upstream provider failed. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"UPSTREAM_FAILED","message":"An upstream provider failed."}}}},"503":{"description":"A required backend is unavailable. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"SERVICE_UNAVAILABLE","message":"A required backend is unavailable."}}}}},"security":[{"BearerAuth":[]}]}},"/health":{"get":{"summary":"Health","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":{"type":"string"},"type":"object","title":"Response Health Health Get"}}}}}}},"/health/ready":{"get":{"summary":"Health Ready","operationId":"health_ready_health_ready_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"ChapterResponse":{"properties":{"title":{"type":"string","title":"Title"},"start_s":{"type":"integer","title":"Start S"}},"type":"object","required":["title","start_s"],"title":"ChapterResponse"},"CreditsResponse":{"properties":{"tier":{"type":"string","enum":["free","pro"],"title":"Tier"},"monthly_allowance":{"type":"integer","title":"Monthly Allowance"},"used_this_month":{"type":"integer","title":"Used This Month"},"remaining":{"type":"integer","title":"Remaining"}},"type":"object","required":["tier","monthly_allowance","used_this_month","remaining"],"title":"CreditsResponse"},"ErrorResponse":{"properties":{"error":{"type":"string","title":"Error"},"message":{"type":"string","title":"Message"}},"type":"object","required":["error","message"],"title":"ErrorResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"SearchBatchItemResponse":{"properties":{"query":{"type":"string","title":"Query"},"videos":{"anyOf":[{"items":{"$ref":"#/components/schemas/SearchVideoResponse"},"type":"array"},{"type":"null"}],"title":"Videos"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"}},"type":"object","required":["query"],"title":"SearchBatchItemResponse"},"SearchBatchResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/SearchBatchItemResponse"},"type":"array","title":"Results"}},"type":"object","required":["results"],"title":"SearchBatchResponse"},"SearchBody":{"properties":{"query":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Query"},"queries":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Queries"},"limit":{"type":"integer","maximum":20.0,"minimum":1.0,"title":"Limit","default":10},"filters":{"anyOf":[{"$ref":"#/components/schemas/SearchFiltersBody"},{"type":"null"}]}},"type":"object","title":"SearchBody"},"SearchFiltersBody":{"properties":{"duration":{"anyOf":[{"type":"string","enum":["short","medium","long"]},{"type":"null"}],"title":"Duration"},"recency":{"anyOf":[{"type":"string","enum":["hour","day","week","month","year"]},{"type":"null"}],"title":"Recency"},"channel":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Channel"}},"type":"object","title":"SearchFiltersBody"},"SearchSingleResponse":{"properties":{"query":{"type":"string","title":"Query"},"videos":{"items":{"$ref":"#/components/schemas/SearchVideoResponse"},"type":"array","title":"Videos"}},"type":"object","required":["query","videos"],"title":"SearchSingleResponse"},"SearchVideoResponse":{"properties":{"youtube_id":{"type":"string","title":"Youtube Id"},"title":{"type":"string","title":"Title"},"channel":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Channel"},"channel_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Channel Id"},"duration_s":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Duration S"},"view_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"View Count"},"published":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Published"},"thumbnail_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Thumbnail Url"},"description_snippet":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description Snippet"},"summary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Summary"}},"type":"object","required":["youtube_id","title"],"title":"SearchVideoResponse"},"SummaryResponse":{"properties":{"youtube_id":{"type":"string","title":"Youtube Id"},"summary":{"type":"string","title":"Summary"}},"type":"object","required":["youtube_id","summary"],"title":"SummaryResponse"},"TranscriptResponse":{"properties":{"youtube_id":{"type":"string","title":"Youtube Id"},"source":{"type":"string","enum":["caption","asr"],"title":"Source"},"language":{"type":"string","title":"Language"},"format":{"type":"string","enum":["markdown","json","plain"],"title":"Format"},"cached":{"type":"boolean","title":"Cached"},"truncated":{"type":"boolean","title":"Truncated"},"transcript":{"anyOf":[{"type":"string"},{"items":{"$ref":"#/components/schemas/TranscriptSegmentResponse"},"type":"array"}],"title":"Transcript"}},"type":"object","required":["youtube_id","source","language","format","cached","truncated","transcript"],"title":"TranscriptResponse"},"TranscriptSegmentResponse":{"properties":{"text":{"type":"string","title":"Text"},"offset_ms":{"type":"integer","title":"Offset Ms"},"duration_ms":{"type":"integer","title":"Duration Ms"}},"type":"object","required":["text","offset_ms","duration_ms"],"title":"TranscriptSegmentResponse"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"VideoResponse":{"properties":{"youtube_id":{"type":"string","title":"Youtube Id"},"title":{"type":"string","title":"Title"},"channel":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Channel"},"channel_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Channel Id"},"duration_s":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Duration S"},"published_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Published At"},"view_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"View Count"},"description":{"type":"string","title":"Description"},"chapters":{"items":{"$ref":"#/components/schemas/ChapterResponse"},"type":"array","title":"Chapters"},"cached":{"type":"boolean","title":"Cached"}},"type":"object","required":["youtube_id","title","description","chapters","cached"],"title":"VideoResponse"}},"securitySchemes":{"BearerAuth":{"type":"http","description":"Required API key: 'Bearer ys_live_...'. Free tier: 1,000 credits/month, no card — get one at https://youtubesearch.dev/login.","scheme":"bearer"}}}}