{"openapi":"3.1.0","info":{"title":"Melchior Video Context API","version":"0.1.0","description":"Paid, agent-ready YouTube transcripts, lexical evidence search, and transcript normalization over x402.","x-guidance":"Use /v1/youtube/search when you need only passages that lexically match a phrase or terms, with timestamp citations. Use /v1/youtube/transcript for the complete transcript and model-sized chunks. Use /v1/transcripts/context when you already have transcript text, WebVTT, SRT, or timestamped segments. Failed extraction responses are not settled."},"servers":[{"url":"https://transcript.melchiorlabs.com"}],"paths":{"/v1/youtube/transcript":{"post":{"summary":"Extract agent-ready context from a public YouTube video","description":"Requires a valid x402 payment signature. Settlement occurs only after a successful response.","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.01"},"protocols":[{"x402":{"network":"eip155:8453","asset":"USDC"}},{"x402":{"network":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","asset":"USDC"}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/YoutubeTranscriptInput"},"example":{"url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","language":"en","maxChunkCharacters":2400}}}},"responses":{"200":{"description":"Structured YouTube transcript context","content":{"application/json":{"schema":{"$ref":"#/components/schemas/YoutubeTranscriptResponse"}}}},"402":{"description":"x402 payment required"},"422":{"description":"Video or captions cannot be processed; payment is not settled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/youtube/search":{"post":{"summary":"Find cited evidence in a public YouTube transcript","description":"Deterministic lexical phrase and term matching. Requires a valid x402 payment signature; settlement occurs only after a successful response, including a valid search with zero matches.","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.005"},"protocols":[{"x402":{"network":"eip155:8453","asset":"USDC"}},{"x402":{"network":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","asset":"USDC"}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/YoutubeSearchInput"},"example":{"url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","query":"never gonna give you up","language":"en","maxResults":5,"contextSegments":1}}}},"responses":{"200":{"description":"Ranked lexical transcript passages; matches may be empty","content":{"application/json":{"schema":{"$ref":"#/components/schemas/YoutubeSearchResponse"}}}},"402":{"description":"x402 payment required"},"422":{"description":"Video or captions cannot be processed; payment is not settled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"summary":"Find cited evidence in a public YouTube transcript (query-string form)","description":"Identical request handling and pricing to POST /v1/youtube/search, expressed as query parameters for callers that cannot send a JSON body. Internally converted to the same validated request; payment headers are preserved. Missing url or query fall back to the discovery example below; a supplied empty or invalid value is not defaulted or coerced and is rejected the same way as an invalid POST body.","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.005"},"protocols":[{"x402":{"network":"eip155:8453","asset":"USDC"}},{"x402":{"network":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","asset":"USDC"}}]},"parameters":[{"name":"url","in":"query","required":false,"schema":{"type":"string","format":"uri","default":"https://www.youtube.com/watch?v=dQw4w9WgXcQ"},"description":"Public youtube.com or youtu.be video URL. Defaults to the discovery example URL when omitted."},{"name":"query","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":500,"default":"never gonna give you up"},"description":"Phrase or terms to match lexically. Defaults to the discovery example query when omitted."},{"name":"language","in":"query","required":false,"schema":{"type":"string","default":"en"},"description":"Preferred caption language code, such as en or es."},{"name":"preferManual","in":"query","required":false,"schema":{"type":"boolean","default":true},"description":"Must be exactly true or false; any other value is rejected rather than coerced."},{"name":"maxResults","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":10,"default":5},"description":"Must be an integer string; non-integer or out-of-range values are rejected."},{"name":"contextSegments","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":5,"default":1},"description":"Neighboring transcript segments included around each lexical match."}],"responses":{"200":{"description":"Ranked lexical transcript passages; matches may be empty","content":{"application/json":{"schema":{"$ref":"#/components/schemas/YoutubeSearchResponse"}}}},"400":{"description":"A supplied query parameter is empty, invalid, or fails validation; payment is not settled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"x402 payment required"},"422":{"description":"Video or captions cannot be processed; payment is not settled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/transcripts/context":{"post":{"summary":"Generate agent-ready context from supplied transcripts","description":"Requires a valid x402 payment signature. Accepts exactly one of transcript text or timestamped segments; text may be plain text, WebVTT, or SRT.","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.003"},"protocols":[{"x402":{"network":"eip155:8453","asset":"USDC"}},{"x402":{"network":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","asset":"USDC"}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranscriptContextInput"},"example":{"text":"WEBVTT\n\n00:00:00.000 --> 00:00:03.000\nHello, agents.","format":"vtt","maxChunkCharacters":2400}}}},"responses":{"200":{"description":"Normalized transcript context","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranscriptContextResponse"}}}},"402":{"description":"x402 payment required"},"422":{"description":"The supplied transcript could not be parsed; payment is not settled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/health":{"get":{"summary":"Check video context service health","responses":{"200":{"description":"Service and extractor are healthy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}}},"components":{"schemas":{"YoutubeTranscriptInput":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"Public youtube.com or youtu.be video URL."},"language":{"type":"string","default":"en","description":"Preferred caption language code, such as en or es."},"preferManual":{"type":"boolean","default":true,"description":"Prefer creator-provided captions over automatic captions when both exist."},"maxChunkCharacters":{"type":"integer","minimum":400,"maximum":8000,"default":2400},"includeSegments":{"type":"boolean","default":true},"includeText":{"type":"boolean","default":true}}},"YoutubeSearchInput":{"type":"object","additionalProperties":false,"required":["url","query"],"properties":{"url":{"type":"string","format":"uri","description":"Public youtube.com or youtu.be video URL."},"query":{"type":"string","minLength":1,"maxLength":500,"description":"Phrase or terms to match lexically. This is not semantic search."},"language":{"type":"string","default":"en","description":"Preferred caption language code, such as en or es."},"preferManual":{"type":"boolean","default":true},"maxResults":{"type":"integer","minimum":1,"maximum":10,"default":5},"contextSegments":{"type":"integer","minimum":0,"maximum":5,"default":1,"description":"Neighboring transcript segments included around each lexical match."}}},"TranscriptContextInput":{"type":"object","oneOf":[{"required":["text"]},{"required":["segments"]}],"properties":{"text":{"type":"string","minLength":1,"maxLength":1000000,"description":"Plain text, WebVTT, or SRT transcript. Mutually exclusive with segments."},"format":{"type":"string","enum":["text","vtt","srt"],"default":"text"},"segments":{"type":"array","minItems":1,"maxItems":20000,"description":"Timestamped transcript segments. Mutually exclusive with text.","items":{"type":"object","required":["startSeconds","endSeconds","text"],"properties":{"startSeconds":{"type":"number","minimum":0,"description":"Segment start time in seconds from the beginning of the source."},"endSeconds":{"type":"number","minimum":0,"description":"Segment end time in seconds from the beginning of the source."},"text":{"type":"string","description":"Transcript text spoken during this segment."}}}},"sourceUrl":{"type":"string","format":"uri","description":"Optional source URL used to build chunk citations."},"maxChunkCharacters":{"type":"integer","minimum":400,"maximum":8000,"default":2400},"includeSegments":{"type":"boolean","default":true},"includeText":{"type":"boolean","default":true}}},"TranscriptSegment":{"type":"object","required":["startSeconds","endSeconds","text"],"properties":{"startSeconds":{"type":"number","minimum":0,"description":"Segment start time in seconds from the beginning of the source."},"endSeconds":{"type":"number","minimum":0,"description":"Segment end time in seconds from the beginning of the source."},"text":{"type":"string","description":"Transcript text spoken during this segment."}}},"TranscriptChunk":{"type":"object","required":["index","startSeconds","endSeconds","text","citation"],"properties":{"index":{"type":"integer","minimum":0,"description":"Zero-based chunk index."},"startSeconds":{"type":"number","minimum":0},"endSeconds":{"type":"number","minimum":0},"text":{"type":"string","description":"Model-sized transcript text for this time range."},"citation":{"type":"object","required":["label"],"properties":{"label":{"type":"string","description":"Human-readable source time range."},"url":{"type":"string","format":"uri","description":"Deep link to the source at the start of this chunk when a source URL is available."}}}}},"YoutubeTranscriptResponse":{"type":"object","required":["requestId","video","transcript","chunks","usage","generatedAt"],"properties":{"requestId":{"type":"string","format":"uuid"},"video":{"type":"object","required":["id","title","url","channel","durationSeconds","publishedAt","thumbnail"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"url":{"type":"string","format":"uri"},"channel":{"type":["string","null"]},"durationSeconds":{"type":"number","minimum":0},"publishedAt":{"type":["string","null"]},"thumbnail":{"type":["string","null"],"format":"uri"}}},"transcript":{"type":"object","required":["language","source","segmentCount"],"properties":{"language":{"type":"string"},"source":{"type":"string","enum":["manual","automatic"]},"segmentCount":{"type":"integer","minimum":0},"text":{"type":"string"},"segments":{"type":"array","items":{"$ref":"#/components/schemas/TranscriptSegment"}}}},"chunks":{"type":"array","items":{"$ref":"#/components/schemas/TranscriptChunk"}},"usage":{"type":"object","required":["characters","estimatedTokens","chunkCount"],"properties":{"characters":{"type":"integer","minimum":0},"estimatedTokens":{"type":"integer","minimum":0},"chunkCount":{"type":"integer","minimum":0},"cache":{"type":"string","enum":["hit","miss"],"description":"Whether this YouTube extraction was served from the transcript cache."}}},"generatedAt":{"type":"string","format":"date-time"}}},"YoutubeSearchMatch":{"type":"object","required":["rank","score","startSeconds","endSeconds","text","matchedTerms","citation"],"properties":{"rank":{"type":"integer","minimum":1,"maximum":10},"score":{"type":"number","minimum":0,"description":"Deterministic lexical score used only to order this response."},"startSeconds":{"type":"number","minimum":0},"endSeconds":{"type":"number","minimum":0},"text":{"type":"string"},"matchedTerms":{"type":"array","items":{"type":"string"}},"citation":{"type":"object","required":["label","url"],"properties":{"label":{"type":"string"},"url":{"type":"string","format":"uri","description":"YouTube deep link at the start of the passage."}}}}},"YoutubeSearchResponse":{"type":"object","required":["requestId","video","query","matches","usage","generatedAt"],"properties":{"requestId":{"type":"string","format":"uuid"},"video":{"type":"object","required":["id","title","url","channel","durationSeconds","publishedAt","thumbnail"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"url":{"type":"string","format":"uri"},"channel":{"type":["string","null"]},"durationSeconds":{"type":"number","minimum":0},"publishedAt":{"type":["string","null"]},"thumbnail":{"type":["string","null"],"format":"uri"}}},"query":{"type":"string"},"matches":{"type":"array","maxItems":10,"items":{"$ref":"#/components/schemas/YoutubeSearchMatch"}},"usage":{"type":"object","required":["candidateSegments","matchedSegments","returnedMatches","cache"],"properties":{"candidateSegments":{"type":"integer","minimum":0,"description":"Transcript segments evaluated."},"matchedSegments":{"type":"integer","minimum":0,"description":"Segments with a positive lexical score."},"returnedMatches":{"type":"integer","minimum":0,"maximum":10},"cache":{"type":"string","enum":["hit","miss"]}}},"generatedAt":{"type":"string","format":"date-time"}}},"TranscriptContextResponse":{"type":"object","required":["requestId","transcript","chunks","usage","generatedAt"],"properties":{"requestId":{"type":"string","format":"uuid"},"transcript":{"type":"object","required":["segmentCount"],"properties":{"segmentCount":{"type":"integer","minimum":0},"text":{"type":"string"},"segments":{"type":"array","items":{"$ref":"#/components/schemas/TranscriptSegment"}}}},"chunks":{"type":"array","items":{"$ref":"#/components/schemas/TranscriptChunk"}},"usage":{"type":"object","required":["characters","estimatedTokens","chunkCount"],"properties":{"characters":{"type":"integer","minimum":0},"estimatedTokens":{"type":"integer","minimum":0},"chunkCount":{"type":"integer","minimum":0}}},"generatedAt":{"type":"string","format":"date-time"}}},"ErrorResponse":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}},"HealthResponse":{"type":"object","required":["status","service","version","revision","extractor","uptimeSeconds","timestamp"],"properties":{"status":{"type":"string","const":"ok"},"service":{"type":"string"},"version":{"type":"string"},"revision":{"type":"string"},"extractor":{"type":"string","enum":["ready","missing"]},"uptimeSeconds":{"type":"integer","minimum":0},"timestamp":{"type":"string","format":"date-time"}}}}},"x-x402":{"networks":["eip155:8453","solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"],"asset":"USDC","resources":{"/v1/youtube/transcript":"$0.01","/v1/youtube/search":"$0.005","/v1/transcripts/context":"$0.003"}}}