YouTube MCP server for your AI agent

Read YouTube transcripts, comments, chapters and channel videos from Claude, Cursor or your own code, with no YouTube API key.

Functions
46
Sign-in
For account actions
Works with
MCP, HTTP, Node, Python

Ask your agent for the transcript of a video and it returns timestamped lines plus the full text. You need only a Bowmark key, with no Google Cloud project and no daily quota.

Try it

const yt = bowmark.providers.youtube;
const { segments, fullText } = await yt.getTranscript({ video: "dQw4w9WgXcQ" });
const { videos } = await yt.listChannelVideos({ channel: "@veritasium" });
return { lines: segments.length, latest: videos.slice(0, 5).map((v) => v.title) };

Add the MCP server to Claude Code with this command, then ask your agent. Other clients are on Installation.

claude mcp add bowmark --transport http https://api.bowmark.ai/mcp --header "Authorization: Bearer $BOWMARK_API_KEY"
Use Bowmark to get the transcript and top comments of this YouTube video: <url>

FAQ

How do I get a YouTube transcript in Claude?

Add Bowmark as an MCP server, then ask Claude for the transcript of a video URL.

Does it need a YouTube API key?

No. Only your Bowmark key.

Can it read videos I do not own?

Yes, anything public. Your own history, Watch later and subscriptions need you to sign in once. See Signed-in sites.

What does it cost?

Your first $10 is free, then you pay per call. See Pricing.

Start with the Quickstart.

Connect

Just YouTube

An MCP server for YouTube alone, with one tool per function. Paste it into Claude, ChatGPT, Cursor or any MCP client as a remote server.

https://api.bowmark.ai/mcp/site/youtube
Every site

One MCP server for YouTube and every other site Bowmark covers. Your agent looks up what it needs and calls it.

https://api.bowmark.ai/mcp
Set it up in your client

Both need a Bowmark API key. The quickstart gets you one and a first result in a few minutes. Functions that need a login use the person's own account: how sign-in works.

Functions

Open a function to see its arguments, what it returns and how to call it.

Read 31
  • findChannelTurn what a person would say about a channel.

    Arguments

    NameTypeRequired
    input{ query: string }Yes

    Returns YoutubeChannelRef | null

    interface YoutubeChannelRef {
      channelId: string;
      url: string;
      handle: string | null; // only set when the source we found it through carries one
      title: string | null;  // only set coming off search; resolve_url gives no title
      subscriberCountText: string | null;
      thumbnail: string | null;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/youtube/findChannel

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.youtube.findChannel({});
  • getChannelA channel's own page as facts: display name, @handle, an abbreviated subscriber count text (YouTube never publishes an exact one), the About tab's…

    Arguments

    NameTypeRequired
    input{ channel: string }Yes

    Returns YoutubeChannel

    interface YoutubeChannelLink {
      title: string;
      url: string; // the real destination, decoded off YouTube's own redirect wrapper
    }
    
    interface YoutubeChannel {
      channelId: string;
      handle: string | null;       // null for a legacy /c/ or /user/ vanity URL with no @handle
      title: string;
      description: string;
      subscriberCountText: string | null; // YouTube's own abbreviated text, e.g. "517M subscribers"
      videoCount: number | null;
      viewCount: number | null;
      country: string | null;
      joinedDate: string | null;   // ISO 8601 date
      links: YoutubeChannelLink[];
      avatar: string | null;
      banner: string | null;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/youtube/getChannel

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.youtube.getChannel({ channel: "UCX6OQ3DkcsbYNE6H8uQQuVA" });
  • getDislikesDislike count, like count and dislike ratio for up to 50 videos at once, no sign-in.

    Arguments

    NameTypeRequired
    input{ videos: string[] }Yes

    Returns YoutubeDislikes

    interface YoutubeDislikeItem {
      video: string;
      likes: number;
      dislikes: number;
      rating: number | null;
      viewCount: number | null;
      ratio: number | null;
      deleted: boolean;
      source: "returnyoutubedislike";
      estimated: true;
    }
    
    interface YoutubeDislikes {
      items: YoutubeDislikeItem[];
      warnings: string[];
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/youtube/getDislikes

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.youtube.getDislikes({ videos: ["dQw4w9WgXcQ"] });
  • getLiveChatThe messages scrolling past a live stream.

    Arguments

    NameTypeRequired
    input{ video: string } | { continuation: string }Yes

    Returns YoutubeLiveChat

    interface YoutubeLiveChatMessage {
      authorName: string;
      authorChannelId: string | null;
      text: string;
      timestampUsec: string; // YouTube's own microsecond epoch timestamp, as a string
    }
    
    interface YoutubeLiveChat {
      open: boolean;               // false when there is no chat to read at all, see notice
      notice: string | null;       // the site's own sentence when open is false
      messages: YoutubeLiveChatMessage[];
      continuation: string | null; // pass back as { continuation } for the next batch; null once the chat has ended
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/youtube/getLiveChat

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.youtube.getLiveChat({ video: "dQw4w9WgXcQ" });
  • getPlayableStreamA link a plain HTML <video> element can play for one ordinary uploaded video: a signed googlevideo.com file with video and audio together (360p mp4)…

    Arguments

    NameTypeRequired
    input{ video: string }Yes

    Returns YoutubePlayableStream

    interface YoutubePlayableStream {
      videoId: string;
      url: string;          // signed googlevideo.com file, video + audio together; set it as a <video> src
      itag: number;         // 18 = 360p mp4, the one every ordinary upload carries
      mimeType: string;
      width: number | null;
      height: number | null;
      qualityLabel: string | null;
      durationMs: number | null;
      expiresAt: string;    // ISO; the URL stops working then, call again for a fresh one
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/youtube/getPlayableStream

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.youtube.getPlayableStream({ video: "dQw4w9WgXcQ" });
  • getPlaybackEvery way to play one video: YouTube's embed (ads included) and every file it serves, 144p to 2160p, split into muxed, video-only and audio-only, so…

    Arguments

    NameTypeRequired
    input{ video: string }Yes

    Returns YoutubePlayback

    interface YoutubePlaybackFile {
      url: string;          // signed googlevideo.com file; a <video> (or <audio>) src, from any address
      mimeType: string;     // "video/mp4", "video/webm", "audio/mp4", "audio/webm"
      codecs: string | null; // "avc1.640028", "vp9", "av01.0.08M.08", "mp4a.40.2", "opus"
      width: number | null;
      height: number | null;
      fps: number | null;
      bitrate: number | null;
      bytes: number | null;
      qualityLabel: string | null; // "1080p60"; null on audio
      itag: number;
    }
    
    interface YoutubePlayback {
      videoId: string;
      title: string | null;
      durationMs: number | null;
      live: boolean;
      // YouTube's own player (youtube-nocookie.com/embed/<id>), ads included; null when the uploader disabled embedding
      embed: { url: string; hasAds: boolean | "unknown"; note: string } | null;
      files: {
        muxed: YoutubePlaybackFile[];     // video + audio in one file (360p): plays alone in a <video>
        videoOnly: YoutubePlaybackFile[]; // every size 144p-2160p: pair ONE with ONE audioOnly file
        audioOnly: YoutubePlaybackFile[];
      };                    // each list tallest/highest-bitrate first; empty for a live, age-gated or blocked video
      expiresAt: string | null; // ISO; the earliest file URL's own expiry, about six hours out
      referrer: "any" | "none" | string;
      warnings: string[];   // why a list is empty or short
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/youtube/getPlayback

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.youtube.getPlayback({ video: "dQw4w9WgXcQ" });
  • getPlaylistA playlist's own facts: title, description, the channel that owns it, how many videos it holds, its view count and when it was last updated.

    Arguments

    NameTypeRequired
    input{ playlist: string }Yes

    Returns YoutubePlaylist

    interface YoutubePlaylist {
      playlistId: string;
      title: string;
      description: string;       // "" when the playlist has none (e.g. a channel's auto Uploads playlist)
      channelId: string | null;
      channelTitle: string | null;
      videoCount: number | null;
      viewCount: number | null;
      lastUpdated: string | null; // YouTube's own text: an absolute date, or "N days ago" on an Uploads playlist
      thumbnail: string | null;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/youtube/getPlaylist

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.youtube.getPlaylist({ playlist: "UUuAXFkgsw1L7xaCfnd5JJOw" });
  • getTranscriptReturns a YouTube video's own caption transcript.

    Arguments

    NameTypeRequired
    inputstring | { video: string }Yes

    Returns YoutubeTranscript

    interface YoutubeTranscriptSegment {
      timestamp: string;
      startSeconds: number;
      text: string;
    }
    
    interface YoutubeTranscript {
      videoId: string;
      segments: YoutubeTranscriptSegment[];
      fullText: string;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/youtube/getTranscript

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.youtube.getTranscript({ video: "dQw4w9WgXcQ" });
  • getVideoEverything the watch page says about one video without playing it: title, channel name and id, full description, view count, like count, length in…

    Arguments

    NameTypeRequired
    input{ video: string }Yes

    Returns YoutubeVideo

    interface YoutubeVideo {
      videoId: string;
      title: string;
      channel: string;  // display name, pass channelId (below), not this, to getChannel / listChannel* / searchWithinChannel
      channelId: string;
      description: string;       // the full watch-page description, not a truncated snippet
      viewCount: number;
      likeCount: number | null;  // null when the site itself hides it on this video
      lengthSeconds: number;
      publishDate: string | null; // ISO 8601
      uploadDate: string | null;  // ISO 8601
      category: string | null;
      keywords: string[];
      isLiveNow: boolean;         // live RIGHT NOW
      isLiveContent: boolean;     // live now, or ever was (stays true for a finished stream's VOD)
      isUnlisted: boolean;
      thumbnails: { url: string; width: number; height: number }[];
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/youtube/getVideo

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.youtube.getVideo({ video: "dQw4w9WgXcQ" });
  • listCaptionTracksWhich languages a video's captions are available in, whether each was written by a human or auto-generated by YouTube, and which one YouTube shows by…

    Arguments

    NameTypeRequired
    input{ video: string }Yes

    Returns YoutubeCaptionTrack[]

    interface YoutubeCaptionTrack {
      languageCode: string;      // e.g. "en", "de-DE", "pt-BR"
      name: string;               // the site's own display name, e.g. "English (auto-generated)"
      isAutoGenerated: boolean;   // true for a track YouTube generated itself, false for a human/uploader one
      isDefault: boolean;         // true for the track getTranscript reads by default
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/youtube/listCaptionTracks

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.youtube.listCaptionTracks({ video: "dQw4w9WgXcQ" });
  • listChannelLiveStreamsA channel's Live tab, the streams it has run, upcoming and past, with their scheduled or actual start times.

    Arguments

    NameTypeRequired
    input{ channel: string } | { continuation: string }Yes

    Returns YoutubeChannelLiveStreamPage

    type YoutubeChannelLiveStreamStatus = "upcoming" | "live" | "ended";
    
    interface YoutubeChannelLiveStream {
      videoId: string;
      url: string;
      title: string;
      status: YoutubeChannelLiveStreamStatus;
      watching: string | null;    // "N watching" (live) or "N waiting" (upcoming); null once ended
      views: string | null;       // YouTube's own abbreviated text, e.g. "94K views", ended only
      scheduledFor: string | null; // e.g. "Scheduled for 9/19/26, 6:00 AM", upcoming only
      published: string | null;   // e.g. "Streamed 1 day ago", ended only
      publishedAgeSeconds: number | null;
      length: string | null;      // e.g. "9:05:30", ended only
      thumbnail: string | null;
    }
    
    interface YoutubeChannelLiveStreamPage {
      streams: YoutubeChannelLiveStream[];
      continuation: string | null; // pass back as { continuation } for the next page; null on the last
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/youtube/listChannelLiveStreams

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.youtube.listChannelLiveStreams({ channel: "UCLA_DiR1FfKNvjuUpBHmylQ" });
  • listChannelPlaylistsThe playlists a channel has published, each with its id, title, video count and thumbnail.

    Arguments

    NameTypeRequired
    input{ channel: string } | { continuation: string }Yes

    Returns YoutubeChannelPlaylistPage

    interface YoutubeChannelPlaylist {
      playlistId: string;
      url: string;
      title: string;
      count: string | null;   // YouTube's own badge text, e.g. "197 videos" or "20 episodes" for a podcast
      updated: string | null; // e.g. "today", "5 days ago", null when the row carries no update stat
      thumbnail: string | null;
    }
    
    interface YoutubeChannelPlaylistPage {
      playlists: YoutubeChannelPlaylist[];
      continuation: string | null; // pass back as { continuation } for the next page; null on the last
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/youtube/listChannelPlaylists

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.youtube.listChannelPlaylists({ channel: "UCupvZG-5ko_eiXAupbDfxWw" });
  • listChannelPostsA channel's Community tab, the text, image and poll posts a creator writes between uploads, with their like and comment counts.

    Arguments

    NameTypeRequired
    input{ channel: string } | { continuation: string }Yes

    Returns YoutubeChannelPostPage

    interface YoutubeChannelPostImage {
      kind: "image";
      images: string[]; // one or several, largest available URL each
    }
    
    interface YoutubeChannelPostPoll {
      kind: "poll";
      choices: string[]; // choice text only, vote counts are hidden from a logged-out viewer
    }
    
    interface YoutubeChannelPostVideo {
      kind: "video"; // a video the channel shared into this tab, may belong to another channel
      videoId: string;
      title: string | null;
    }
    
    type YoutubeChannelPostAttachment =
      | YoutubeChannelPostImage
      | YoutubeChannelPostPoll
      | YoutubeChannelPostVideo
      | null;
    
    interface YoutubeChannelPost {
      postId: string;
      url: string;
      author: string | null;
      text: string | null;
      published: string | null;   // YouTube's own phrase, e.g. "2 weeks ago", "(edited)" appended on an edited post
      publishedAgeSeconds: number | null;
      likeCount: string | null;    // YouTube's own abbreviated text, e.g. "407K", no "likes"
      commentCount: string | null; // YouTube's own abbreviated text, e.g. "6.7K", no "comments"
      attachment: YoutubeChannelPostAttachment;
    }
    
    interface YoutubeChannelPostPage {
      posts: YoutubeChannelPost[];
      continuation: string | null; // pass back as { continuation } for the next page; null on the last
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/youtube/listChannelPosts

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.youtube.listChannelPosts({ channel: "UCupvZG-5ko_eiXAupbDfxWw" });
  • listChannelShortsA channel's Shorts tab, its vertical short-form videos, which sit in their own tab with their own item shape and never appear in the Videos tab.

    Arguments

    NameTypeRequired
    input{ channel: string } | { continuation: string }Yes

    Returns YoutubeChannelShortPage

    interface YoutubeChannelShort {
      videoId: string;
      url: string;                // https://www.youtube.com/shorts/<id>, a Short has no watch?v= URL
      title: string;
      views: string | null;       // YouTube's own abbreviated text WITH "views" already in it, e.g. "13M views"
      thumbnail: string | null;
      // no publish date, no length, neither exists anywhere in the Shorts-tab shape
    }
    
    interface YoutubeChannelShortPage {
      shorts: YoutubeChannelShort[];
      continuation: string | null; // pass back as { continuation } for the next page; null on the last
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/youtube/listChannelShorts

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.youtube.listChannelShorts({ channel: "UCX6OQ3DkcsbYNE6H8uQQuVA" });
  • listChannelVideosWhat a channel has published, newest first and paged.

    Arguments

    NameTypeRequired
    input{ channel: string } | { continuation: string }Yes

    Returns YoutubeChannelVideoPage

    interface YoutubeChannelVideo {
      videoId: string;
      url: string;
      title: string;
      views: string | null;       // YouTube's own abbreviated text, e.g. "101M views"
      published: string | null;   // YouTube's own phrase, e.g. "11 days ago"
      publishedAgeSeconds: number | null;
      length: string | null;      // e.g. "23:28"; null for a live stream
      thumbnail: string | null;
    }
    
    interface YoutubeChannelVideoPage {
      videos: YoutubeChannelVideo[];
      continuation: string | null; // pass back as { continuation } for the next page; null on the last
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/youtube/listChannelVideos

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.youtube.listChannelVideos({ channel: "UCX6OQ3DkcsbYNE6H8uQQuVA" });
  • listChaptersA video's own chapter markers.

    Arguments

    NameTypeRequired
    input{ video: string }Yes

    Returns YoutubeChapter[]

    interface YoutubeChapter {
      title: string;
      startSeconds: number;    // pass to watch?v=<id>&t=<startSeconds>s
      timeDescription: string; // YouTube's own display text, e.g. "1:03:10"
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/youtube/listChapters

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.youtube.listChapters({ video: "rfscVS0vtbw" });
  • listCommentRepliesThe replies under one comment thread, which YouTube hides behind a "N replies" button and never ships with the thread itself.

    Arguments

    NameTypeRequired
    input{ continuation: string }Yes

    Returns YoutubeCommentReplyPage

    interface YoutubeComment {
      commentId: string;
      author: string;
      authorChannelId: string | null;
      text: string;
      likeCount: string;         // YouTube's own abbreviated text, e.g. "316K", never an exact number
      publishedTime: string;     // YouTube's own relative phrase, e.g. "1 year ago"
      replyCount: number;
      isPinned: boolean;
      isHeartedByCreator: boolean;
      repliesContinuation: string | null; // pass to listCommentReplies as { continuation }; null when replyCount is 0
    }
    
    interface YoutubeCommentReply {
      commentId: string;
      author: string;
      authorChannelId: string | null;
      text: string;
      likeCount: string;      // same convention as YoutubeComment.likeCount
      publishedTime: string;  // YouTube's own relative phrase, e.g. "1 year ago"
      isHeartedByCreator: boolean;
    }
    
    interface YoutubeCommentReplyPage {
      replies: YoutubeCommentReply[];
      continuation: string | null; // pass back as { continuation } for the next page; null on the last
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/youtube/listCommentReplies

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.youtube.listCommentReplies({});
  • listCommentsWhat people said under a video.

    Arguments

    NameTypeRequired
    input{ video: string; sortBy?: "top" | "newest" } | { continuation: string }Yes

    Returns YoutubeCommentPage

    interface YoutubeComment {
      commentId: string;
      author: string;
      authorChannelId: string | null;
      text: string;
      likeCount: string;         // YouTube's own abbreviated text, e.g. "316K", never an exact number
      publishedTime: string;     // YouTube's own relative phrase, e.g. "1 year ago"
      replyCount: number;
      isPinned: boolean;
      isHeartedByCreator: boolean;
      repliesContinuation: string | null; // pass to listCommentReplies as { continuation }; null when replyCount is 0
    }
    
    interface YoutubeCommentPage {
      comments: YoutubeComment[];
      continuation: string | null; // pass back as { continuation } for the next page; null on the last
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/youtube/listComments

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.youtube.listComments({ video: "dQw4w9WgXcQ" });
  • listHashtagVideosThe videos under a hashtag.

    Arguments

    NameTypeRequired
    input{ hashtag: string }Yes

    Returns YoutubeSearchVideo[]

    interface YoutubeSearchVideo {
      videoId: string;
      url: string;
      title: string;
      channel: string | null;  // display name, pass channelId (below), not this, to getChannel / listChannel* / searchWithinChannel
      channelId: string | null;
      published: string | null;          // YouTube's own phrase, e.g. "4 weeks ago"
      publishedAgeSeconds: number | null; // that phrase in seconds, to order newest-first
      length: string | null;             // e.g. "22:28"; null for a live stream
      lengthSeconds: number | null;      // length in whole seconds; null exactly when length is
      views: number | null;
      thumbnail: string | null;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/youtube/listHashtagVideos

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.youtube.listHashtagVideos({ hashtag: "gaming" });
  • listHomeFeedThe videos on the signed-in account's own YouTube home page.

    Arguments

    NameTypeRequired
    input{ limit?: number }No

    Returns YoutubeSearchVideo[]

    interface YoutubeSearchVideo {
      videoId: string;
      url: string;
      title: string;
      channel: string | null;  // display name, pass channelId (below), not this, to getChannel / listChannel* / searchWithinChannel
      channelId: string | null;
      published: string | null;          // YouTube's own phrase, e.g. "4 weeks ago"
      publishedAgeSeconds: number | null; // that phrase in seconds, to order newest-first
      length: string | null;             // e.g. "22:28"; null for a live stream
      lengthSeconds: number | null;      // length in whole seconds; null exactly when length is
      views: number | null;
      thumbnail: string | null;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/youtube/listHomeFeed

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.youtube.listHomeFeed();
  • listLikedVideosThe videos the signed-in account has liked.

    Arguments

    NameTypeRequired
    input{ continuation?: string; limit?: number }No

    Returns YoutubePlaylistVideoPage

    interface YoutubePlaylistVideo {
      videoId: string;
      url: string;
      title: string;
      channelId: string | null;   // the PUBLISHING channel, which can differ from the playlist owner
      channelTitle: string | null;
      views: string | null;       // YouTube's own abbreviated text, e.g. "4.9M views"
      published: string | null;   // YouTube's own phrase, e.g. "5 years ago"
      publishedAgeSeconds: number | null;
      length: string | null;      // e.g. "1:00:02"; null for a live stream
      thumbnail: string | null;
      percentWatched?: number;    // watch history: how much of it this account watched, 0-100 (100 = finished)
    }
    
    interface YoutubePlaylistVideoPage {
      videos: YoutubePlaylistVideo[];
      continuation: string | null; // pass back as { continuation } for the next page; null on the last
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/youtube/listLikedVideos

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.youtube.listLikedVideos();
  • listMyVideosThe videos on the signed-in account's own channel, private and unlisted ones included, with each one's privacy and processing status.

    Arguments

    NameTypeRequired
    input{ limit?: number; pageToken?: string }No

    Returns YoutubeMyVideoPage

    interface YoutubeMyVideo {
      videoId: string;
      title: string;
      description: string | null;
      privacy: "private" | "unlisted" | "public" | null;
      status: string | null;       // Studio's own processing state, lower-cased with its prefix dropped, the site's own labels, read the values off a result, never guess one from prose
      lengthSeconds: number | null; // null while a fresh upload is still processing
      tags: string[];
      thumbnail: string | null;
      createdAt: string | null;    // ISO timestamp
      url: string;
      studioUrl: string;           // where the channel owner edits it by hand
    }
    
    interface YoutubeMyVideoPage {
      videos: YoutubeMyVideo[];
      nextPageToken: string | null; // pass back as { pageToken } for the next page; null on the last
      total: number | null;         // how many videos the channel has
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/youtube/listMyVideos

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.youtube.listMyVideos({});
  • listPlaylistVideosThe videos inside a playlist, in the playlist's own order and paged.

    Arguments

    NameTypeRequired
    input{ playlist: string } | { continuation: string }Yes

    Returns YoutubePlaylistVideoPage

    interface YoutubePlaylistVideo {
      videoId: string;
      url: string;
      title: string;
      channelId: string | null;   // the PUBLISHING channel, which can differ from the playlist owner
      channelTitle: string | null;
      views: string | null;       // YouTube's own abbreviated text, e.g. "4.9M views"
      published: string | null;   // YouTube's own phrase, e.g. "5 years ago"
      publishedAgeSeconds: number | null;
      length: string | null;      // e.g. "1:00:02"; null for a live stream
      thumbnail: string | null;
      percentWatched?: number;    // watch history: how much of it this account watched, 0-100 (100 = finished)
    }
    
    interface YoutubePlaylistVideoPage {
      videos: YoutubePlaylistVideo[];
      continuation: string | null; // pass back as { continuation } for the next page; null on the last
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/youtube/listPlaylistVideos

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.youtube.listPlaylistVideos({ playlist: "UUuAXFkgsw1L7xaCfnd5JJOw" });
  • listRelatedVideosThe videos YouTube itself puts next to this one.

    Arguments

    NameTypeRequired
    input{ video: string } | { continuation: string }Yes

    Returns YoutubeRelatedVideoPage

    interface YoutubeRelatedVideo {
      videoId: string;
      url: string;
      title: string;
      channel: string | null;  // display name, pass channelId (below), not this, to getChannel / listChannel* / searchWithinChannel
      channelId: string | null;
      views: string | null;       // YouTube's own abbreviated text, e.g. "206M", the bare number, not "206M views"
      published: string | null;   // YouTube's own phrase, e.g. "16y ago"
      publishedAgeSeconds: number | null;
      length: string | null;      // e.g. "3:24"; null for a live stream
      thumbnail: string | null;
    }
    
    interface YoutubeRelatedVideoPage {
      videos: YoutubeRelatedVideo[];
      continuation: string | null; // pass back as { continuation } for the next page; null on the last
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/youtube/listRelatedVideos

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.youtube.listRelatedVideos({ video: "dQw4w9WgXcQ" });
  • listStreamFormatsThe renditions a video is actually available in.

    Arguments

    NameTypeRequired
    input{ video: string }Yes

    Returns YoutubeStreamFormat[]

    interface YoutubeStreamFormat {
      itag: number;
      mimeType: string;
      bitrate: number;
      width: number | null;
      height: number | null;
      fps: number | null;
      qualityLabel: string | null;
      contentLength: string | null;  // null on the muxed entry, YouTube does not publish it there
      approxDurationMs: string | null;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/youtube/listStreamFormats

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.youtube.listStreamFormats({ video: "dQw4w9WgXcQ" });
  • listSubscriptionsThe channels the signed-in account subscribes to.

    Arguments

    None.

    Returns YoutubeChannelRef[]

    interface YoutubeChannelRef {
      channelId: string;
      url: string;
      handle: string | null; // only set when the source we found it through carries one
      title: string | null;  // only set coming off search; resolve_url gives no title
      subscriberCountText: string | null;
      thumbnail: string | null;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/youtube/listSubscriptions

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.youtube.listSubscriptions();
  • listWatchHistoryWhat the signed-in account has watched, newest first, with how much of each video was watched.

    Arguments

    NameTypeRequired
    input{ continuation?: string; limit?: number }No

    Returns YoutubePlaylistVideoPage

    interface YoutubePlaylistVideo {
      videoId: string;
      url: string;
      title: string;
      channelId: string | null;   // the PUBLISHING channel, which can differ from the playlist owner
      channelTitle: string | null;
      views: string | null;       // YouTube's own abbreviated text, e.g. "4.9M views"
      published: string | null;   // YouTube's own phrase, e.g. "5 years ago"
      publishedAgeSeconds: number | null;
      length: string | null;      // e.g. "1:00:02"; null for a live stream
      thumbnail: string | null;
      percentWatched?: number;    // watch history: how much of it this account watched, 0-100 (100 = finished)
    }
    
    interface YoutubePlaylistVideoPage {
      videos: YoutubePlaylistVideo[];
      continuation: string | null; // pass back as { continuation } for the next page; null on the last
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/youtube/listWatchHistory

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.youtube.listWatchHistory();
  • listWatchLaterThe signed-in account's Watch Later queue.

    Arguments

    NameTypeRequired
    input{ continuation?: string; limit?: number }No

    Returns YoutubePlaylistVideoPage

    interface YoutubePlaylistVideo {
      videoId: string;
      url: string;
      title: string;
      channelId: string | null;   // the PUBLISHING channel, which can differ from the playlist owner
      channelTitle: string | null;
      views: string | null;       // YouTube's own abbreviated text, e.g. "4.9M views"
      published: string | null;   // YouTube's own phrase, e.g. "5 years ago"
      publishedAgeSeconds: number | null;
      length: string | null;      // e.g. "1:00:02"; null for a live stream
      thumbnail: string | null;
      percentWatched?: number;    // watch history: how much of it this account watched, 0-100 (100 = finished)
    }
    
    interface YoutubePlaylistVideoPage {
      videos: YoutubePlaylistVideo[];
      continuation: string | null; // pass back as { continuation } for the next page; null on the last
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/youtube/listWatchLater

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.youtube.listWatchLater();
  • searchWithinChannelSearch one channel's own videos rather than the whole site.

    Arguments

    NameTypeRequired
    input{ channel: string; query: string } | { continuation: string }Yes

    Returns YoutubeChannelSearchPage

    interface YoutubeSearchVideo {
      videoId: string;
      url: string;
      title: string;
      channel: string | null;  // display name, pass channelId (below), not this, to getChannel / listChannel* / searchWithinChannel
      channelId: string | null;
      published: string | null;          // YouTube's own phrase, e.g. "4 weeks ago"
      publishedAgeSeconds: number | null; // that phrase in seconds, to order newest-first
      length: string | null;             // e.g. "22:28"; null for a live stream
      lengthSeconds: number | null;      // length in whole seconds; null exactly when length is
      views: number | null;
      thumbnail: string | null;
    }
    
    interface YoutubeChannelSearchPage {
      videos: YoutubeSearchVideo[];
      continuation: string | null; // pass back as { continuation } for the next page; null on the last
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/youtube/searchWithinChannel

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.youtube.searchWithinChannel({
      channel: "UCX6OQ3DkcsbYNE6H8uQQuVA",
      query: "clean water"
    });
  • suggestSearchesYouTube's own autocomplete for a partial query.

    Arguments

    NameTypeRequired
    input{ query: string }Yes

    Returns string[]

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/youtube/suggestSearches

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.youtube.suggestSearches({ query: "lofi" });
Act 15
  • addToPlaylistAdd a video to, or remove one from, one of the signed-in account's own playlists.

    Arguments

    NameTypeRequired
    input{ playlist: string; video?: string; videos?: string[] }Yes

    Returns YoutubePlaylistEdit

    interface YoutubePlaylistEdit {
      playlistId: string;
      added: string[];             // what was sent and accepted, in order, not a per-video receipt
      url: string;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/youtube/addToPlaylist

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.youtube.addToPlaylist({});
  • createChannelCreates the signed-in Google account's YouTube CHANNEL, using the account's own name and profile photo.

    Arguments

    None.

    Returns YoutubeCreatedChannel

    interface YoutubeCreatedChannel {
      channelId: string;
      name: string;                // the account's own Google profile name
      url: string;
      alreadyExisted: boolean;     // true when the account already had one; nothing was created
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/youtube/createChannel

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.youtube.createChannel();
  • createPlaylistCreate a playlist on the signed-in account.

    Arguments

    NameTypeRequired
    input{ title: string; description?: string; privacy?: "private" | "unlisted" | "public" }Yes

    Returns YoutubeCreatedPlaylist

    interface YoutubeCreatedPlaylist {
      playlistId: string;
      title: string;
      privacy: "private" | "unlisted" | "public";
      url: string;                 // open this to see it
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/youtube/createPlaylist

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.youtube.createPlaylist({});
  • deleteCommentDelete a top-level comment the signed-in account wrote.

    Arguments

    NameTypeRequired
    input{ video: string; commentId: string }Yes

    Returns { video: string; commentId: string; deleted: boolean }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/youtube/deleteComment

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.youtube.deleteComment({});
  • deletePlaylistPermanently delete one of the signed-in account's own playlists.

    Arguments

    NameTypeRequired
    input{ playlist: string }Yes

    Returns YoutubeDeletedPlaylist

    interface YoutubeDeletedPlaylist {
      playlistId: string;
      deleted: boolean;            // permanent, no undo
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/youtube/deletePlaylist

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.youtube.deletePlaylist({});
  • deleteVideoPermanently delete one of the signed-in account's own videos.

    Arguments

    NameTypeRequired
    input{ video: string }Yes

    Returns YoutubeDeletedVideo

    interface YoutubeDeletedVideo {
      videoId: string;
      status: "deleted" | "deleting"; // either way it is gone and cannot be undone
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/youtube/deleteVideo

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.youtube.deleteVideo({});
  • likeVideoLike or dislike a video as the signed-in account, or clear the rating.

    Arguments

    NameTypeRequired
    input{ video: string; rating: "like" | "dislike" | "none" }Yes

    Returns { video: string; rating: "like" | "dislike" | "none" }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/youtube/likeVideo

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.youtube.likeVideo({});
  • postCommentLeave a comment on a video as the signed-in account.

    Arguments

    NameTypeRequired
    input{ video: string; text: string }Yes

    Returns { video: string; commentId: string | null; text: string }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/youtube/postComment

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.youtube.postComment({});
  • removeFromPlaylistRemove one or more videos from one of the signed-in account's own playlists.

    Arguments

    NameTypeRequired
    input{ playlist: string; video?: string; videos?: string[] }Yes

    Returns YoutubePlaylistEdit

    interface YoutubePlaylistEdit {
      playlistId: string;
      added: string[];             // what was sent and accepted, in order, not a per-video receipt
      url: string;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/youtube/removeFromPlaylist

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.youtube.removeFromPlaylist({});
  • replyToCommentReply to an existing comment as the signed-in account.

    Arguments

    NameTypeRequired
    input{ video: string; commentId: string; text: string }Yes

    Returns { video: string; repliedTo: string; commentId: string | null; text: string }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/youtube/replyToComment

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.youtube.replyToComment({});
  • setThumbnailSet a custom thumbnail image on one of the signed-in account's own videos.

    Arguments

    NameTypeRequired
    input{ video: string; file?: string; url?: string }Yes

    Returns YoutubeThumbnailSet

    interface YoutubeThumbnailSet {
      videoId: string;
      thumbnail: string | null;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/youtube/setThumbnail

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.youtube.setThumbnail({});
  • subscribeToChannelSubscribe the signed-in account to a channel, or unsubscribe.

    Arguments

    NameTypeRequired
    input{ channel: string; subscribe?: boolean }Yes

    Returns { channel: string; subscribed: boolean }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/youtube/subscribeToChannel

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.youtube.subscribeToChannel({});
  • updatePlaylistChange the title, description or privacy of one of the signed-in account's own playlists.

    Arguments

    NameTypeRequired
    input{ playlist: string; title?: string; description?: string; privacy?: string }Yes

    Returns YoutubePlaylistEdit

    interface YoutubePlaylistEdit {
      playlistId: string;
      added: string[];             // what was sent and accepted, in order, not a per-video receipt
      url: string;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/youtube/updatePlaylist

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.youtube.updatePlaylist({});
  • updateVideoChange the title, description, tags, category or privacy of one of the signed-in account's own videos.

    Arguments

    NameTypeRequired
    input{ video: string; title?: string; description?: string; tags?: string[]; categoryId?: number; privacy?: "private" | "unlisted" | "public" }Yes

    Returns YoutubeVideoEdit

    interface YoutubeMyVideo {
      videoId: string;
      title: string;
      description: string | null;
      privacy: "private" | "unlisted" | "public" | null;
      status: string | null;       // Studio's own processing state, lower-cased with its prefix dropped, the site's own labels, read the values off a result, never guess one from prose
      lengthSeconds: number | null; // null while a fresh upload is still processing
      tags: string[];
      thumbnail: string | null;
      createdAt: string | null;    // ISO timestamp
      url: string;
      studioUrl: string;           // where the channel owner edits it by hand
    }
    
    interface YoutubeVideoEdit {
      videoId: string;
      updated: string[];           // the fields YouTube confirmed it changed, e.g. ["title", "privacy"]
      video: YoutubeMyVideo;       // the video as Studio reads it back afterwards
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/youtube/updateVideo

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.youtube.updateVideo({});
  • uploadVideoUpload a video file to the signed-in account's own channel, with its title, description, tags, category and privacy.

    Arguments

    NameTypeRequired
    input{ file?: string; url?: string; title: string; description?: string; tags?: string[]; categoryId?: number; privacy?: "private" | "unlisted" | "public" }Yes

    Returns YoutubeUploadedVideo

    interface YoutubeUploadedVideo {
      videoId: string;
      title: string;
      privacy: "private" | "unlisted" | "public";
      url: string;
      studioUrl: string;
      status: "processing";        // YouTube is still encoding it; listMyVideos shows when it is "processed"
      warnings: string[];          // non-empty only when the video uploaded but its tags/category did not stick
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/youtube/uploadVideo

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.youtube.uploadVideo({});

Use it from code