{"openapi":"3.1.2","info":{"title":"TubeSignal YouTube Evidence API","version":"1.3.0","description":"Search up to 20 recent videos in a channel corpus or one public video. Return an overview, multiple distinct answers, timestamped source excerpts, translations, provenance, and explicit abstentions. TubeSignal reports what was said; it does not verify external truth."},"externalDocs":{"description":"Agent integration guide and runnable examples","url":"https://tubesignal.net/agents/docs"},"servers":[{"url":"https://tubesignal.net"}],"paths":{"/api/v1/evidence/channels":{"get":{"operationId":"listPreparedEvidenceChannels","summary":"List prepared channel corpora available for channel queries","responses":{"200":{"description":"Prepared channels, source languages, corpus windows, and suggested questions"}}}},"/api/v1/evidence/query":{"post":{"operationId":"getYouTubeEvidence","summary":"Get multiple grounded answers from one video or a recent channel corpus","description":"Use one of the fixed demo targets anonymously, or send a bearer key for any supported public video. A channel query searches its cached 30-day corpus of up to 20 videos. Fewer answers than answer_count may be returned when evidence is limited.","security":[{},{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Recommended for retries. Reusing a key with any changed request field returns 409.","schema":{"type":"string","maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["question"],"oneOf":[{"required":["video_url"],"not":{"required":["channel_id"]}},{"required":["channel_id"],"not":{"required":["video_url"]}}],"properties":{"video_url":{"type":"string","format":"uri"},"channel_id":{"type":"string","pattern":"^UC[A-Za-z0-9_-]{22}$"},"question":{"type":"string","minLength":3,"maxLength":1000},"response_language":{"enum":["ko","en"],"description":"Language for the overview, answers, and optional translated_text. Original excerpt text is never replaced."},"evidence_limit":{"type":"integer","minimum":1,"maximum":6,"default":3},"answer_count":{"type":"integer","minimum":1,"maximum":4,"default":1,"description":"Requested number of distinct grounded findings. The service may return fewer rather than invent unsupported answers."}}},"examples":{"recentChannel":{"summary":"Three findings across a 30-day channel corpus","value":{"channel_id":"UC6kZpTl39-_SqfBrF1-N2oQ","question":"최근 한 달 영상에서 한국 시장과 주요 기업의 전망을 좌우할 변수로 무엇이 반복해서 언급됐나요?","response_language":"ko","answer_count":3,"evidence_limit":6}},"oneVideo":{"summary":"One answer about a public video","value":{"video_url":"https://www.youtube.com/watch?v=zMvBMfj4cSQ","question":"How did the speaker describe the shift toward persistent AI coworkers?","response_language":"en","answer_count":1,"evidence_limit":3}}}}}},"responses":{"200":{"description":"Answered or explicit non-billable abstention","content":{"application/json":{"schema":{"type":"object","required":["schema_version","status","answer","answers","external_truth_status","evidence","coverage","provenance","usage","request_id"],"properties":{"schema_version":{"const":"2026-09-11"},"status":{"enum":["answered","insufficient_evidence","transcript_unavailable","video_unavailable","unsupported_language","acquisition_failed","policy_restricted","rate_limited","budget_exceeded","internal_error"]},"answer":{"type":["string","null"],"description":"Backwards-compatible overview of the supported findings."},"answers":{"type":"array","maxItems":4,"description":"Distinct grounded findings. Each item points to one-based indexes in the evidence array.","items":{"type":"object","required":["id","title","answer","evidence_indices"],"properties":{"id":{"type":"string"},"title":{"type":"string","maxLength":120},"answer":{"type":"string","maxLength":2000},"evidence_indices":{"type":"array","minItems":1,"maxItems":6,"uniqueItems":true,"items":{"type":"integer","minimum":1,"maximum":6}}}}},"external_truth_status":{"const":"not_evaluated"},"reason":{"type":"string"},"request_id":{"type":"string","format":"uuid"},"evidence":{"type":"array","maxItems":6,"items":{"type":"object","required":["start_seconds","end_seconds","text","watch_url","relation"],"properties":{"start_seconds":{"type":"number","minimum":0},"end_seconds":{"type":"number","minimum":0},"text":{"type":"string","maxLength":500,"description":"Evidence in the source transcript's original language; never replaced by a translation."},"translated_text":{"type":"string","maxLength":700,"description":"Optional display translation when response_language differs from the source transcript language."},"watch_url":{"type":"string","format":"uri"},"relation":{"const":"supports_that_the_speaker_said_this"},"video_id":{"type":"string"},"video_title":{"type":["string","null"]},"published_at":{"type":["string","null"]},"source_language":{"type":["string","null"]}}}},"coverage":{"type":"object"},"provenance":{"type":"object"},"usage":{"type":"object","description":"Current beta trials are free. quota_units_consumed reports allowance usage; replayed identifies an idempotent replay.","properties":{"billable_units":{"const":0},"charged_usd":{"const":0},"quota_units_consumed":{"type":"integer","enum":[0,1]},"replayed":{"type":"boolean"},"newly_charged_usd":{"const":0}}}}}}}},"401":{"description":"Missing, invalid, expired, or revoked key"},"429":{"description":"Successful-pack quota exhausted"},"503":{"description":"Budget or kill switch paused the experiment"}}}},"/api/v1/trials":{"post":{"summary":"Send an email verification code","responses":{"202":{"description":"Verification email accepted"}}}},"/api/v1/trials/verify":{"post":{"summary":"Verify email and issue a one-time-visible trial key","responses":{"201":{"description":"Trial key issued"}}}},"/api/v1/keys/revoke":{"post":{"summary":"Revoke the presented key","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Revoked"}}}},"/api/v1/paid-access-requests":{"post":{"deprecated":true,"summary":"Email support@tubesignal.net to purchase additional usage; submission does not charge","responses":{"201":{"description":"Legacy request stored"}}}},"/api/v1/takedown-requests":{"post":{"summary":"Submit a rights or deletion review request","responses":{"201":{"description":"Request stored for manual review"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"TubeSignal trial API key"}},"schemas":{"EvidencePack":{"type":"object","required":["schema_version","status","answer","answers","external_truth_status","evidence","coverage","provenance","usage","request_id"],"properties":{"schema_version":{"const":"2026-09-11"},"status":{"enum":["answered","insufficient_evidence","transcript_unavailable","video_unavailable","unsupported_language","acquisition_failed","policy_restricted","rate_limited","budget_exceeded","internal_error"]},"answer":{"type":["string","null"],"description":"Backwards-compatible overview of the supported findings."},"answers":{"type":"array","maxItems":4,"description":"Distinct grounded findings. Each item points to one-based indexes in the evidence array.","items":{"type":"object","required":["id","title","answer","evidence_indices"],"properties":{"id":{"type":"string"},"title":{"type":"string","maxLength":120},"answer":{"type":"string","maxLength":2000},"evidence_indices":{"type":"array","minItems":1,"maxItems":6,"uniqueItems":true,"items":{"type":"integer","minimum":1,"maximum":6}}}}},"external_truth_status":{"const":"not_evaluated"},"reason":{"type":"string"},"request_id":{"type":"string","format":"uuid"},"evidence":{"type":"array","maxItems":6,"items":{"type":"object","required":["start_seconds","end_seconds","text","watch_url","relation"],"properties":{"start_seconds":{"type":"number","minimum":0},"end_seconds":{"type":"number","minimum":0},"text":{"type":"string","maxLength":500,"description":"Evidence in the source transcript's original language; never replaced by a translation."},"translated_text":{"type":"string","maxLength":700,"description":"Optional display translation when response_language differs from the source transcript language."},"watch_url":{"type":"string","format":"uri"},"relation":{"const":"supports_that_the_speaker_said_this"},"video_id":{"type":"string"},"video_title":{"type":["string","null"]},"published_at":{"type":["string","null"]},"source_language":{"type":["string","null"]}}}},"coverage":{"type":"object"},"provenance":{"type":"object"},"usage":{"type":"object","description":"Current beta trials are free. quota_units_consumed reports allowance usage; replayed identifies an idempotent replay.","properties":{"billable_units":{"const":0},"charged_usd":{"const":0},"quota_units_consumed":{"type":"integer","enum":[0,1]},"replayed":{"type":"boolean"},"newly_charged_usd":{"const":0}}}}}}}}