{"version":"v1","scope":"customer","routes":[{"version":"v1","path":"/api/v1/channels/discover","legacyPath":"/api/channels/discover","methods":["GET"],"auth":"user","sideEffects":"read","visibility":"external-beta","summary":"Find imported channels and saved-transcript coverage.","queryParams":[{"name":"q","description":"Channel title, @handle, ID or YouTube channel URL.","placeholder":"apple","required":true,"example":"apple"},{"name":"limit","description":"Maximum channels to return (1–50, default 10).","placeholder":"10"}],"responseSchema":{"type":"object","description":"Matching visible imported channels.","properties":{"total":{"type":"number","description":"Number of channels returned; not a corpus-wide match count."},"channels":{"type":"array","description":"Channels available to the caller.","items":{"type":"object","description":"Channel discovery result.","properties":{"id":{"type":"string","description":"YouTube channel ID, usable in searches and questions."},"title":{"type":"string","description":"Channel title."},"handle":{"type":"string","description":"Canonical @handle when known."},"thumbnail":{"type":"string","description":"Channel thumbnail URL."},"videoCount":{"type":"number","description":"Number of public imported videos."},"transcriptVideoCount":{"type":"number","description":"Number of public videos with a saved transcript. This does not guarantee vector indexing is complete."},"url":{"type":"string","description":"Channel page on AskChannelAI."}}}}}}},{"version":"v1","path":"/api/v1/channels/import","legacyPath":"/api/channels/import","methods":["POST"],"auth":"user","sideEffects":"enqueue","visibility":"external-beta","summary":"Import a YouTube channel.","requestSchema":{"type":"object","description":"Channel import request.","properties":{"channelUrl":{"type":"string","description":"YouTube channel URL, @handle, or UC… channel ID. Returns 404 if no such channel exists on YouTube.","example":"@apple"}},"required":["channelUrl"]},"responseSchema":{"type":"object","description":"Import result.","properties":{"channel":{"type":"object","description":"The registered channel record."},"isNew":{"type":"string","description":"Whether the channel was newly registered by this call."},"runId":{"type":"string","description":"Import run ID when processing started immediately."},"queued":{"type":"string","description":"True when another import is in progress and this one was queued."}}}},{"version":"v1","path":"/api/v1/channels/{id}","legacyPath":"/api/channels/{id}","methods":["GET"],"auth":"user","sideEffects":"read","visibility":"external-beta","summary":"Get channel details and processing state.","pathParamExamples":{"id":"apple"},"responseSchema":{"type":"object","description":"Channel metadata and processing state.","properties":{"id":{"type":"string","description":"YouTube channel ID."},"handle":{"type":"string","description":"Channel @handle."},"title":{"type":"string","description":"Channel title."},"status":{"type":"string","description":"Import or processing status."},"total_videos":{"type":"number","description":"Known video count."},"last_updated":{"type":"string","description":"When the channel was last checked for new videos."}}}},{"version":"v1","path":"/api/v1/channels/{id}/import-progress","legacyPath":"/api/channels/{id}/import-progress","methods":["GET"],"auth":"user","sideEffects":"enqueue","visibility":"external-beta","summary":"Get cached channel import progress.","pathParamExamples":{"id":"apple"},"responseSchema":{"type":"object","description":"Current import progress.","properties":{"status":{"type":"string","description":"Import status."},"imported":{"type":"number","description":"Imported video count."},"total":{"type":"number","description":"Expected total count."}}}},{"version":"v1","path":"/api/v1/channels/{id}/job-stats","legacyPath":"/api/channels/{id}/job-stats","methods":["GET"],"auth":"user","sideEffects":"read","visibility":"external-beta","summary":"Live job throughput and ETA.","pathParamExamples":{"id":"apple"}},{"version":"v1","path":"/api/v1/channels/{id}/search-quotes","legacyPath":"/api/channels/{id}/search-quotes","methods":["GET"],"auth":"user","sideEffects":"read","visibility":"external-beta","summary":"Full-text quote search.","pathParamExamples":{"id":"apple"},"queryParams":[{"name":"q","description":"Search query. Wrap in double quotes for an exact phrase search.","placeholder":"airpods","required":true,"example":"airpods"},{"name":"page","description":"1-based page number.","placeholder":"1"},{"name":"pageSize","description":"Results per page (1-50).","placeholder":"10"}],"responseSchema":{"type":"object","description":"Paginated quote matches.","properties":{"enabled":{"type":"string","description":"Whether this channel has a searchable transcript index."},"total":{"type":"number","description":"Total matching segments across all pages."},"page":{"type":"number","description":"Current page number."},"pageSize":{"type":"number","description":"Results returned per page."},"results":{"type":"array","description":"Matching transcript segments, highest-ranked first.","items":{"type":"object","description":"Quote match.","properties":{"videoId":{"type":"string","description":"YouTube video ID."},"videoTitle":{"type":"string","description":"Video title."},"startTime":{"type":"number","description":"Segment start time in seconds."},"text":{"type":"string","description":"Full transcript segment text."},"snippet":{"type":"string","description":"Highlighted snippet with matches wrapped in << >>."}}}}}}},{"version":"v1","path":"/api/v1/search-quotes-hybrid","legacyPath":"/api/search-quotes-hybrid","methods":["GET"],"auth":"user","sideEffects":"read","visibility":"external-beta","summary":"Multi-channel hybrid quote search (FTS + dense + RRF). One Postgres FTS call for all channels.","queryParams":[{"name":"channels","description":"Comma-separated channel ids or handles to search (required). Alias: channelIds. Max 50.","placeholder":"UCxxx,UCyyy","required":true,"example":"UCxxx,UCyyy"},{"name":"q","description":"Primary search query / alias. Optional if aliases is set.","placeholder":"NVDA","example":"NVDA"},{"name":"aliases","description":"Comma-separated probes OR'd across FTS + dense (e.g. NVDA,NVIDIA,英伟达). Combined with q.","placeholder":"NVDA,NVIDIA,英伟达","example":"NVDA,NVIDIA,英伟达"},{"name":"page","description":"1-based page over the fused ranking.","placeholder":"1"},{"name":"pageSize","description":"Results per page (1-50).","placeholder":"10"},{"name":"mode","description":"Retrieval mode: hybrid (default), fts, or dense.","placeholder":"hybrid","example":"hybrid"},{"name":"sinceDays","description":"Optional lookback: only videos uploaded within this many days.","placeholder":"30","example":"30"},{"name":"minDenseScore","description":"Floor on the dense (Pinecone cosine) branch only, applied before RRF. Default 0. Alias: minScore. Does not filter results[].score.","placeholder":"0","example":"0"}],"responseSchema":{"type":"object","description":"Hybrid-fused quote matches across channels.","properties":{"enabled":{"type":"boolean","description":"Whether a valid retrieval query was attempted; an empty index can return no matches."},"total":{"type":"number","description":"Public fused candidates before pagination; not a corpus-wide match count."},"totalScope":{"type":"string","description":"The bounded candidate pool covered by total.","enum":["retrieved_candidates"]},"scoreType":{"type":"string","description":"Score scale: rank fusion in hybrid, lexical rank in fts, cosine in dense.","enum":["rrf","ts_rank","cosine"]},"page":{"type":"number","description":"Current page number."},"pageSize":{"type":"number","description":"Results returned per page."},"mode":{"type":"string","description":"Mode that produced the ranking.","enum":["hybrid","fts","dense"]},"channelIds":{"type":"array","description":"Resolved channel ids included in the search.","items":{"type":"string","description":"YouTube channel id."}},"branches":{"type":"object","description":"Raw candidate counts per branch before fusion.","properties":{"fts":{"type":"number","description":"FTS branch hit count."},"dense":{"type":"number","description":"Dense branch hit count."}}},"results":{"type":"array","description":"Fused quote hits, highest ranking score first.","items":{"type":"object","description":"Hybrid quote match.","properties":{"channelId":{"type":"string","description":"YouTube channel id that produced this hit."},"videoId":{"type":"string","description":"YouTube video ID."},"videoTitle":{"type":"string","description":"Video title."},"startTime":{"type":"number","description":"Segment start time in seconds."},"endTime":{"type":"number","description":"Segment end time in seconds."},"text":{"type":"string","description":"Transcript passage text."},"snippet":{"type":"string","description":"Passage with alias hits wrapped in << >> for highlighting."},"score":{"type":"number","description":"Ranking score — RRF when mode=hybrid (Σ 1/(k+rank)); ts_rank when mode=fts; Pinecone cosine when mode=dense. Not comparable across modes."},"sources":{"type":"array","description":"Which branches contributed this hit.","items":{"type":"string","description":"Branch id.","enum":["fts","dense"]}},"uploadDate":{"type":"string","description":"Video upload time (ISO), when known."}}}}}}},{"version":"v1","path":"/api/v1/channel/qa/{channelId}","legacyPath":"/api/channel/qa/{channelId}","methods":["POST"],"auth":"user","sideEffects":"write","visibility":"external-beta","summary":"Ask a cited question over a channel.","pathParamExamples":{"channelId":"apple"},"requestSchema":{"type":"object","description":"Channel question request.","properties":{"question":{"type":"string","description":"Question to answer from channel evidence.","example":"What is the latest Macbook Pro model and what upgrades does it have over the previous version?"},"platform":{"type":"string","description":"Optional. Pre-render the answer for a chat platform; adds a ready-to-send `rendered` field to the response (the raw answer + citations are still returned).","enum":["telegram","discord","whatsapp","slack"],"example":"telegram"}},"required":["question"]},"responseSchema":{"type":"object","description":"Answer with citations.","properties":{"answer":{"type":"string","description":"The generated answer as clean prose. Contains NO inline citation markers — every citation is in the separate citations array."},"citations":{"type":"array","description":"Citations supporting the answer, each anchored to a video timestamp.","items":{"type":"object","description":"Citation.","properties":{"videoId":{"type":"string","description":"YouTube video ID."},"videoTitle":{"type":"string","description":"Video title."},"startTime":{"type":"number","description":"Citation start time in seconds."},"endTime":{"type":"number","description":"Citation end time in seconds."},"text":{"type":"string","description":"The cited transcript passage."},"url":{"type":"string","description":"Deep link to the video at the cited timestamp."}}}},"rendered":{"type":"string","description":"Only present when `platform` is set: the answer pre-formatted for that chat app (HTML for telegram, mrkdwn for slack/whatsapp). For discord this is a { content, embeds } object instead of a string."}}}},{"version":"v1","path":"/api/v1/search/instant","legacyPath":"/api/search/instant","methods":["GET"],"auth":"user","sideEffects":"read","visibility":"external-beta","summary":"Instant text search over videos.","queryParams":[{"name":"q","description":"Keyword search query.","placeholder":"macbook pro","required":true,"example":"macbook pro"},{"name":"channel_id","description":"Optional channel handle or ID scope. The @ prefix is optional — apple and @apple are equivalent.","placeholder":"apple","example":"apple"},{"name":"limit","description":"Maximum results to return.","placeholder":"20"}]}]}