{"openapi":"3.1.0","info":{"title":"YouTubeSearch API","description":"Clean YouTube data for AI agents: search, transcripts, summaries.\n\nAuth: `Authorization: Bearer ys_live_...` (free tier: 1,000 credits/month, no card). Keyless requests serve cached content only.\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. Keyless tier serves cached transcripts only.","operationId":"get_transcript_v1_videos__video_id__transcript_get","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":{"type":"object","additionalProperties":true,"title":"Response Get Transcript V1 Videos  Video Id  Transcript Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/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. Keyless tier: allowed, IP rate-limited.","operationId":"search_endpoint_v1_search_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchBody"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Search Endpoint V1 Search Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/videos/{video_id}":{"get":{"summary":"Video metadata","description":"Native metadata + chapters, cache-first (7-day refresh). Credits: 1. Keyless tier serves cached metadata only.","operationId":"get_video_v1_videos__video_id__get","parameters":[{"name":"video_id","in":"path","required":true,"schema":{"type":"string","title":"Video Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Video V1 Videos  Video Id  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/videos/{video_id}/summary":{"get":{"summary":"Structured summary","description":"Structured knowledge document (executive summary, key points, detailed summary, insights, timestamps, action items, resources). Select fields with ?sections=. Credits: 1 cached, 5 cold (cold generation also queues an async premium upgrade). Keyless tier serves cached only.","operationId":"get_summary_v1_videos__video_id__summary_get","parameters":[{"name":"video_id","in":"path","required":true,"schema":{"type":"string","title":"Video Id"}},{"name":"sections","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sections"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Summary V1 Videos  Video Id  Summary Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/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","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Get Credits V1 Credits Get"}}}}}}},"/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"}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"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"},"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"}}}}