{"openapi":"3.1.0","info":{"title":"agent-transcript","version":"0.1.0","description":"YouTube search + transcript API for AI agents. Free search and free transcript, no account, no API key, JSON out. Paid transcript $0.01/call and paid search $0.005/call, USDC on Base via x402."},"servers":[{"url":"https://agent-transcript.fly.dev"}],"tags":[{"name":"free","description":"No payment, no account."},{"name":"paid","description":"x402 pay-per-call, USDC on Base."},{"name":"discovery","description":"Health and machine-readable specs."}],"paths":{"/health":{"get":{"tags":["discovery"],"operationId":"health","summary":"Health check","responses":{"200":{"description":"Service is up.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"}}}}}}}}},"/agent/v1/youtube-search":{"get":{"tags":["free"],"operationId":"youtubeSearch","summary":"Free YouTube search","description":"Returns structured video results. Cost $0, no API key.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"Search query."},{"name":"max_results","in":"query","required":false,"schema":{"type":"integer","default":5,"minimum":1},"description":"Max results to return."}],"responses":{"200":{"description":"Search results.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"description":"Missing or invalid query.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Search failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/agent/v1/transcript":{"get":{"tags":["free"],"operationId":"getTranscript","summary":"Free YouTube transcript","description":"Free caption tiers only. A video with no captions returns 404 and never falls back to a paid service.","parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string","format":"uri"},"description":"YouTube URL."},{"name":"lang","in":"query","required":false,"schema":{"type":"string","default":"auto","enum":["auto","en","zh"]},"description":"Caption language."}],"responses":{"200":{"description":"Structured transcript.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranscriptResponse"}}}},"400":{"description":"Not a YouTube URL or bad URL.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Video has no captions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/agent/v1/youtube-search-paid":{"get":{"tags":["paid"],"operationId":"youtubeSearchPaid","summary":"Paid YouTube search ($0.005/call)","description":"Same search as the free endpoint, paid per call. Payment is verified first, results are fetched second, and settlement happens only after results exist, so a failed search never charges.","x-payment-info":{"scheme":"exact","network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","currency":"USDC","amount":"0.005","maxAmountRequired":"5000","maxTimeoutSeconds":60,"payTo":"0xacc70e0892191ea599e52f7ea5ecdc78f046048c"},"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"Search query."},{"name":"max_results","in":"query","required":false,"schema":{"type":"integer","default":5,"minimum":1}},{"name":"X-PAYMENT","in":"header","required":false,"schema":{"type":"string"},"description":"x402 payment header. Omit it and the endpoint returns 402 with the payment challenge."}],"responses":{"200":{"description":"Search results, paid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"description":"Invalid query; not settled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required. Retry with an X-PAYMENT header carrying a verified x402 payment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"},"example":{"x402Version":1,"error":"payment_required","accepts":[{"scheme":"exact","network":"eip155:8453","maxAmountRequired":"5000","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","maxTimeoutSeconds":60,"extra":{"name":"USD Coin","version":"2"},"payTo":"0xacc70e0892191ea599e52f7ea5ecdc78f046048c"}]}}}},"502":{"description":"Search failed; not settled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/agent/v1/transcript-paid":{"get":{"tags":["paid"],"operationId":"getTranscriptPaid","summary":"Paid YouTube transcript ($0.01/call)","description":"Never serves a transcript without a verified and settled $0.01 Base USDC payment. A no-caption video is verified but never settled, so it never charges.","x-payment-info":{"scheme":"exact","network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","currency":"USDC","amount":"0.01","maxAmountRequired":"10000","maxTimeoutSeconds":60,"payTo":"0xacc70e0892191ea599e52f7ea5ecdc78f046048c"},"parameters":[{"name":"url","in":"query","required":false,"schema":{"type":"string","format":"uri"},"description":"YouTube URL. May be omitted on a bare probe, which returns 402."},{"name":"lang","in":"query","required":false,"schema":{"type":"string","default":"auto","enum":["auto","en","zh"]}},{"name":"X-PAYMENT","in":"header","required":false,"schema":{"type":"string"},"description":"x402 payment header. Omit it and the endpoint returns 402 with the payment challenge."}],"responses":{"200":{"description":"Structured transcript, paid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranscriptResponse"}}}},"400":{"description":"Not a YouTube URL.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required. Retry with an X-PAYMENT header carrying a verified x402 payment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"},"example":{"x402Version":1,"error":"payment_required","accepts":[{"scheme":"exact","network":"eip155:8453","maxAmountRequired":"10000","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","maxTimeoutSeconds":60,"extra":{"name":"USD Coin","version":"2"},"payTo":"0xacc70e0892191ea599e52f7ea5ecdc78f046048c"}]}}}},"404":{"description":"No captions; not settled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/openapi.json":{"get":{"tags":["discovery"],"operationId":"openapiSpec","summary":"This OpenAPI 3.1 document","responses":{"200":{"description":"OpenAPI document."}}}},"/x402.json":{"get":{"tags":["discovery"],"operationId":"x402Spec","summary":"x402 payment spec","responses":{"200":{"description":"Payment spec."}}}}},"components":{"schemas":{"Segment":{"type":"object","properties":{"start":{"type":"number"},"end":{"type":"number"},"text":{"type":"string"}}},"TranscriptResponse":{"type":"object","properties":{"video_id":{"type":"string"},"transcript":{"type":"string"},"segments":{"type":"array","items":{"$ref":"#/components/schemas/Segment"}},"source":{"type":"string"},"cost_usd":{"type":"number"}}},"SearchResult":{"type":"object","properties":{"video_id":{"type":"string"},"title":{"type":["string","null"]}}},"SearchResponse":{"type":"object","properties":{"query":{"type":"string"},"results":{"type":"array","items":{"$ref":"#/components/schemas/SearchResult"}},"count":{"type":"integer"},"source":{"type":"string"},"cost_usd":{"type":"number"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"detail":{"type":"string"}}},"PaymentRequired":{"type":"object","properties":{"x402Version":{"type":"integer"},"error":{"type":"string"},"accepts":{"type":"array","items":{"type":"object","properties":{"scheme":{"type":"string"},"network":{"type":"string"},"maxAmountRequired":{"type":"string"},"asset":{"type":"string"},"payTo":{"type":"string"},"maxTimeoutSeconds":{"type":"integer"},"extra":{"type":"object"}}}},"resource":{"type":"string"}}}}}}