Reddit MCP server for AI agents

Let Claude, ChatGPT or your own agent read and act on Reddit: 40 typed functions through one MCP server. No Reddit API key needed.

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

Connect

Just Reddit

An MCP server for Reddit 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/reddit
Every site

One MCP server for Reddit 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 22
  • browseSubredditsLists communities without a query.

    Arguments

    NameTypeRequired
    list"popular" | "new" | { list?: "popular" | "new"; limit?: number; after?: string }No

    Returns RedditSubredditBrowse

    interface RedditSubredditInfo {
      id: string;                  // "t5_…"
      name: string;                // canonical casing, what every other function takes
      title: string;
      description: string | null;  // the short public description
      sidebar: string | null;      // the long markdown sidebar
      subscribers: number | null;
      activeUsers: number | null;
      createdAt: string;
      type: string;                // public, private, restricted, archived, gold_only, …
      over18: boolean;
      quarantined: boolean;
      url: string;
      iconUrl: string | null;
      bannerUrl: string | null;
      submissionType: string | null; // "any", "link", "self"
      language: string | null;
      viewer: { subscribed: boolean; moderator: boolean; banned: boolean } | null;
    }
    
    interface RedditSubredditBrowse {
      list: "popular" | "new";
      subreddits: RedditSubredditInfo[];
      nextCursor: string | null;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/reddit/browseSubreddits

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.reddit.browseSubreddits("popular");
  • findPostsByUrlGiven a link, returns the Reddit threads that submitted or discussed it.

    Arguments

    NameTypeRequired
    urlstring | { url: string; exact?: boolean }Yes

    Returns RedditPostsByUrl

    interface RedditPost {
      id: string;                  // fullname "t3_…", what getPost, vote, savePostOrComment and postComment take
      title: string;
      author: string | null;       // null = deleted account
      subreddit: string;
      permalink: string;           // the discussion
      url: string;                 // what the post points AT; the permalink for a self post
      domain: string | null;
      isSelfPost: boolean;
      selfText: string | null;     // markdown body of a self post
      score: number;
      upvoteRatio: number | null;
      numComments: number;
      createdAt: string;
      editedAt: string | null;
      flair: string | null;        // the flair's display text, submitPost's `flairText`
      flairId: string | null;      // the flair TEMPLATE id, submitPost's `flairId` (same id listPostFlairs returns)
      over18: boolean;
      spoiler: boolean;
      stickied: boolean;           // pinned by the moderators
      locked: boolean;
      archived: boolean;
      removed: string | null;      // reddit's removal reason, e.g. "moderator"; null = still up
      thumbnail: string | null;
      isVideo: boolean;
      viewer: { vote: "up" | "down" | null; saved: boolean; hidden: boolean } | null; // null when not signed in
    }
    
    interface RedditPostsByUrl {
      url: string;                 // as passed
      matched: { url: string; posts: number }[]; // every spelling asked, and how many threads it matched
      via: "search" | "duplicates";  // duplicates = a reddit thread URL was passed
      posts: RedditPost[];         // most-discussed first
      warnings: string[];          // search only: one line per thread reddit refused; the matches are incomplete by these
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/reddit/findPostsByUrl

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.reddit.findPostsByUrl("<url>");
  • getCommentRepliesExpands a branch of a thread that getPost could not return.

    Arguments

    NameTypeRequired
    args{ post: string; cursor?: { path: string; query: Record<string, string>; cursor: string }; parent?: string; subreddit?: string; sort?: "confidence" | "top" | "new" | "controversial" | "old" | "qa" }Yes

    Returns RedditCommentReplies

    interface RedditComment {
      id: string;                  // fullname "t1_…"
      author: string | null;       // null = deleted account
      body: string;                // markdown as written (plain rendered text from getPost)
      score: number | null;        // null while reddit hides a new comment's score
      createdAt: string;
      editedAt: string | null;
      permalink: string;           // this exact reply
      parentId: string;            // "t1_…" for a reply, "t3_…" for a top-level comment
      postId: string;              // "t3_…" of the thread
      subreddit: string;
      depth: number;
      isSubmitter: boolean;        // written by the thread's own author
      stickied: boolean;
      distinguished: string | null; // "moderator", "admin"
      replies: RedditComment[];    // nested, as reddit nests them
      moreReplies: { count: number; ids: string[] } | null;
      viewer: { vote: "up" | "down" | null; saved: boolean } | null;
    }
    
    interface RedditCommentReplies {
      postId: string;
      parent: RedditComment | null; // the comment a "continue this thread" branch hangs under
      comments: RedditComment[];    // nested
      more: { count: number; cursor: string } | null; // still folded, pass this cursor again
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/reddit/getCommentReplies

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.reddit.getCommentReplies({
      post: "t3_1wjydiy",
      parent: "t1_pamvkbg",
      subreddit: "SubredditDrama"
    });
  • getHomeFeedThe signed-in caller's own Reddit home feed.

    Arguments

    NameTypeRequired
    opts{ sort?: "best" | "hot" | "new" | "top" | "rising"; time?: "hour" | "day" | "week" | "month" | "year" | "all"; limit?: number; after?: string }No

    Returns RedditHomeFeed

    interface RedditPost {
      id: string;                  // fullname "t3_…", what getPost, vote, savePostOrComment and postComment take
      title: string;
      author: string | null;       // null = deleted account
      subreddit: string;
      permalink: string;           // the discussion
      url: string;                 // what the post points AT; the permalink for a self post
      domain: string | null;
      isSelfPost: boolean;
      selfText: string | null;     // markdown body of a self post
      score: number;
      upvoteRatio: number | null;
      numComments: number;
      createdAt: string;
      editedAt: string | null;
      flair: string | null;        // the flair's display text, submitPost's `flairText`
      flairId: string | null;      // the flair TEMPLATE id, submitPost's `flairId` (same id listPostFlairs returns)
      over18: boolean;
      spoiler: boolean;
      stickied: boolean;           // pinned by the moderators
      locked: boolean;
      archived: boolean;
      removed: string | null;      // reddit's removal reason, e.g. "moderator"; null = still up
      thumbnail: string | null;
      isVideo: boolean;
      viewer: { vote: "up" | "down" | null; saved: boolean; hidden: boolean } | null; // null when not signed in
    }
    
    interface RedditHomeFeed {
      sort: "best" | "hot" | "new" | "top" | "rising";
      time: "hour" | "day" | "week" | "month" | "year" | "all" | null; // only for "top"
      posts: RedditPost[];         // viewer carries the caller's vote / saved / hidden
      nextCursor: string | null;   // pass as `after`; null = no more
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/reddit/getHomeFeed

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.reddit.getHomeFeed();
  • getMyAccountReturns the signed-in caller's own account.

    Arguments

    None.

    Returns RedditMyAccount

    interface RedditMyAccount {
      id: string;                  // "t2_…"
      name: string;
      createdAt: string;
      linkKarma: number;
      commentKarma: number;
      totalKarma: number;
      iconUrl: string | null;
      hasMail: boolean;            // unread mail waiting
      inboxCount: number;
      hasModMail: boolean;
      isModerator: boolean;
      hasPremium: boolean;
      hasVerifiedEmail: boolean;
      over18: boolean;
      suspended: boolean;
      canCreateSubreddit: boolean;
      url: string;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/reddit/getMyAccount

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.reddit.getMyAccount();
  • getPostReturns one Reddit submission and the discussion under it.

    Arguments

    NameTypeRequired
    poststring | {post: string, sort?: "confidence"|"top"|"new"|"controversial"|"old"|"qa", limit?: number}Yes

    Returns RedditThread

    interface RedditPost {
      id: string;                  // fullname "t3_…", what getPost, vote, savePostOrComment and postComment take
      title: string;
      author: string | null;       // null = deleted account
      subreddit: string;
      permalink: string;           // the discussion
      url: string;                 // what the post points AT; the permalink for a self post
      domain: string | null;
      isSelfPost: boolean;
      selfText: string | null;     // markdown body of a self post
      score: number;
      upvoteRatio: number | null;
      numComments: number;
      createdAt: string;
      editedAt: string | null;
      flair: string | null;        // the flair's display text, submitPost's `flairText`
      flairId: string | null;      // the flair TEMPLATE id, submitPost's `flairId` (same id listPostFlairs returns)
      over18: boolean;
      spoiler: boolean;
      stickied: boolean;           // pinned by the moderators
      locked: boolean;
      archived: boolean;
      removed: string | null;      // reddit's removal reason, e.g. "moderator"; null = still up
      thumbnail: string | null;
      isVideo: boolean;
      viewer: { vote: "up" | "down" | null; saved: boolean; hidden: boolean } | null; // null when not signed in
    }
    
    interface RedditComment {
      id: string;                  // fullname "t1_…"
      author: string | null;       // null = deleted account
      body: string;                // markdown as written (plain rendered text from getPost)
      score: number | null;        // null while reddit hides a new comment's score
      createdAt: string;
      editedAt: string | null;
      permalink: string;           // this exact reply
      parentId: string;            // "t1_…" for a reply, "t3_…" for a top-level comment
      postId: string;              // "t3_…" of the thread
      subreddit: string;
      depth: number;
      isSubmitter: boolean;        // written by the thread's own author
      stickied: boolean;
      distinguished: string | null; // "moderator", "admin"
      replies: RedditComment[];    // nested, as reddit nests them
      moreReplies: { count: number; ids: string[] } | null;
      viewer: { vote: "up" | "down" | null; saved: boolean } | null;
    }
    
    interface RedditThread {
      post: RedditPost;
      sort: "confidence" | "top" | "new" | "controversial" | "old" | "qa";
      comments: RedditComment[];   // nested
      moreComments: { count: number; ids: string[] } | null; // top-level comments still folded once limit was reached; ids empty
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/reddit/getPost

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.reddit.getPost("t3_w1ve97");
  • getSubredditReturns the facts about one community rather than its content.

    Arguments

    NameTypeRequired
    namestringYes

    Returns RedditSubredditProfile

    interface RedditSubredditInfo {
      id: string;                  // "t5_…"
      name: string;                // canonical casing, what every other function takes
      title: string;
      description: string | null;  // the short public description
      sidebar: string | null;      // the long markdown sidebar
      subscribers: number | null;
      activeUsers: number | null;
      createdAt: string;
      type: string;                // public, private, restricted, archived, gold_only, …
      over18: boolean;
      quarantined: boolean;
      url: string;
      iconUrl: string | null;
      bannerUrl: string | null;
      submissionType: string | null; // "any", "link", "self"
      language: string | null;
      viewer: { subscribed: boolean; moderator: boolean; banned: boolean } | null;
    }
    
    interface RedditSubredditAccess {
      readable: boolean;           // check THIS first
      reason: string | null;       // reddit's own word: "private", "banned", "quarantined", "gold_only"
    }
    
    interface RedditSubredditProfile {
      name: string;
      access: RedditSubredditAccess;
      info: RedditSubredditInfo | null;   // null when reddit will not describe it
      quarantineMessage: string | null;
      newestPostAt: string | null;
      postsLastWeek: number | null;       // among its 25 newest posts
      warnings: string[];                 // one line per one of those 25 that reddit refused; the liveness answer is approximate by these
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/reddit/getSubreddit

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.reddit.getSubreddit("webscraping");
  • getSubredditPostsReturns a community's own front page.

    Arguments

    NameTypeRequired
    inputstring | {subreddit: string, sort?: "hot"|"new"|"top"|"rising"|"controversial", time?: "hour"|"day"|"week"|"month"|"year"|"all", limit?: number, after?: string}Yes

    Returns RedditSubredditPostsResult

    interface RedditPost {
      id: string;                  // fullname "t3_…", what getPost, vote, savePostOrComment and postComment take
      title: string;
      author: string | null;       // null = deleted account
      subreddit: string;
      permalink: string;           // the discussion
      url: string;                 // what the post points AT; the permalink for a self post
      domain: string | null;
      isSelfPost: boolean;
      selfText: string | null;     // markdown body of a self post
      score: number;
      upvoteRatio: number | null;
      numComments: number;
      createdAt: string;
      editedAt: string | null;
      flair: string | null;        // the flair's display text, submitPost's `flairText`
      flairId: string | null;      // the flair TEMPLATE id, submitPost's `flairId` (same id listPostFlairs returns)
      over18: boolean;
      spoiler: boolean;
      stickied: boolean;           // pinned by the moderators
      locked: boolean;
      archived: boolean;
      removed: string | null;      // reddit's removal reason, e.g. "moderator"; null = still up
      thumbnail: string | null;
      isVideo: boolean;
      viewer: { vote: "up" | "down" | null; saved: boolean; hidden: boolean } | null; // null when not signed in
    }
    
    interface RedditSubredditPostsResult {
      subreddit: string;
      sort: "hot" | "new" | "top" | "rising" | "controversial";
      time: "hour" | "day" | "week" | "month" | "year" | "all" | null; // null on sorts with no window
      posts: RedditPost[];
      nextCursor: string | null;
      warnings: string[];          // sort "new" only: one line per post reddit refused; the page is incomplete by these
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/reddit/getSubredditPosts

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.reddit.getSubredditPosts({
      subreddit: "programming",
      sort: "top",
      time: "year",
      limit: 5
    });
  • getSubredditRulesReturns one community's posting rules.

    Arguments

    NameTypeRequired
    subredditstring | { subreddit: string }Yes

    Returns RedditRules

    interface RedditRule {
      name: string;
      description: string;         // markdown
      appliesTo: "posts" | "comments" | "both";
      violationReason: string | null;
      priority: number;
      createdAt: string | null;
    }
    
    interface RedditRules {
      subreddit: string;
      rules: RedditRule[];
      siteRules: string[];
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/reddit/getSubredditRules

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.reddit.getSubredditRules("AskHistorians");
  • getUserReturns a redditor's public profile.

    Arguments

    NameTypeRequired
    namestringYes

    Returns RedditUserProfile | RedditUserAbsent

    interface RedditUserInfo {
      id: string;                  // "t2_…"
      name: string;
      createdAt: string;
      linkKarma: number;
      commentKarma: number;
      totalKarma: number;
      iconUrl: string | null;
      description: string | null;  // the profile's own blurb
      isEmployee: boolean;
      isModerator: boolean;
      verified: boolean;
      hasPremium: boolean;
      suspended: boolean;
      over18Profile: boolean;
      url: string;
    }
    
    interface RedditUserProfile extends RedditUserInfo {
      state: "active";
      trophies: { name: string; description: string | null; grantedAt: string | null }[];
    }
    
    interface RedditUserAbsent {
      state: "not_found" | "suspended"; // not_found = deleted OR never existed; reddit answers both identically
      name: string;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/reddit/getUser

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.reddit.getUser("spez");
  • getUserCommentsReturns the comments one redditor has written, newest or top first, each with its body, score, the subreddit and thread it sits in, and a permalink.

    Arguments

    NameTypeRequired
    userstring | { user: string; sort?: "new" | "top" | "hot" | "controversial"; time?: "hour" | "day" | "week" | "month" | "year" | "all"; limit?: number; after?: string }Yes

    Returns RedditUserComments

    interface RedditComment {
      id: string;                  // fullname "t1_…"
      author: string | null;       // null = deleted account
      body: string;                // markdown as written (plain rendered text from getPost)
      score: number | null;        // null while reddit hides a new comment's score
      createdAt: string;
      editedAt: string | null;
      permalink: string;           // this exact reply
      parentId: string;            // "t1_…" for a reply, "t3_…" for a top-level comment
      postId: string;              // "t3_…" of the thread
      subreddit: string;
      depth: number;
      isSubmitter: boolean;        // written by the thread's own author
      stickied: boolean;
      distinguished: string | null; // "moderator", "admin"
      replies: RedditComment[];    // nested, as reddit nests them
      moreReplies: { count: number; ids: string[] } | null;
      viewer: { vote: "up" | "down" | null; saved: boolean } | null;
    }
    
    interface RedditUserComment extends RedditComment {
      thread: { id: string; title: string; permalink: string | null; author: string | null; url: string | null; numComments: number | null };
    }
    
    interface RedditUserComments {
      user: string;
      sort: "new" | "top" | "hot" | "controversial";
      time: string | null;
      comments: RedditUserComment[];
      nextCursor: string | null;
      window: string;
      warnings: string[];
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/reddit/getUserComments

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.reddit.getUserComments({ user: "spez", limit: 5 });
  • getUserPostsReturns the submissions one redditor has made, newest or top first, with the same per-post fields the search and listing functions return plus the…

    Arguments

    NameTypeRequired
    userstring | { user: string; sort?: "new" | "top" | "hot" | "controversial"; time?: "hour" | "day" | "week" | "month" | "year" | "all"; limit?: number; after?: string }Yes

    Returns RedditUserPosts

    interface RedditPost {
      id: string;                  // fullname "t3_…", what getPost, vote, savePostOrComment and postComment take
      title: string;
      author: string | null;       // null = deleted account
      subreddit: string;
      permalink: string;           // the discussion
      url: string;                 // what the post points AT; the permalink for a self post
      domain: string | null;
      isSelfPost: boolean;
      selfText: string | null;     // markdown body of a self post
      score: number;
      upvoteRatio: number | null;
      numComments: number;
      createdAt: string;
      editedAt: string | null;
      flair: string | null;        // the flair's display text, submitPost's `flairText`
      flairId: string | null;      // the flair TEMPLATE id, submitPost's `flairId` (same id listPostFlairs returns)
      over18: boolean;
      spoiler: boolean;
      stickied: boolean;           // pinned by the moderators
      locked: boolean;
      archived: boolean;
      removed: string | null;      // reddit's removal reason, e.g. "moderator"; null = still up
      thumbnail: string | null;
      isVideo: boolean;
      viewer: { vote: "up" | "down" | null; saved: boolean; hidden: boolean } | null; // null when not signed in
    }
    
    interface RedditUserPosts {
      user: string;
      sort: "new" | "top" | "hot" | "controversial";
      time: string | null;         // only for top / controversial
      posts: RedditPost[];
      nextCursor: string | null;
      window: string;              // says: a recent window (~1,000 per sort), not the full history
      warnings: string[];
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/reddit/getUserPosts

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.reddit.getUserPosts({ user: "spez", limit: 5 });
  • getWikiPageReturns a subreddit's wiki page.

    Arguments

    NameTypeRequired
    subredditstring | { subreddit: string; page?: string }Yes

    Returns RedditWikiPage | RedditWikiAbsent

    interface RedditWikiPage {
      state: "ok";
      subreddit: string;
      page: string;
      markdown: string;
      revisedAt: string | null;
      revisedBy: string | null;
      length: number;              // characters of markdown
      long: boolean;               // over ~20 KB, still returned whole
    }
    
    interface RedditWikiAbsent {
      state: "no_such_community" | "community_unavailable" | "private" | "not_viewable" | "page_not_found";
      subreddit: string;
      page?: string;
      reason: string | null;       // reddit's own word, e.g. "MAY_NOT_VIEW"
      pages?: string[];            // on page_not_found: the pages that do exist
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/reddit/getWikiPage

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.reddit.getWikiPage({ subreddit: "AskHistorians", page: "index" });
  • listInboxReads the signed-in caller's inbox.

    Arguments

    NameTypeRequired
    opts{ filter?: "all" | "unread" | "messages" | "mentions" | "comment_replies" | "post_replies"; limit?: number; after?: string }No

    Returns RedditInbox

    interface RedditMessage {
      id: string;                  // "t4_…" private message, "t1_…" reply or mention
      kind: "message" | "comment_reply" | "post_reply" | "username_mention" | "other";
      author: string | null;
      subject: string;
      body: string;
      createdAt: string;
      unread: boolean;
      subreddit: string | null;
      permalink: string | null;    // the comment, for replies and mentions
    }
    
    interface RedditInbox {
      filter: "all" | "unread" | "messages" | "mentions" | "comment_replies" | "post_replies";
      messages: RedditMessage[];
      nextCursor: string | null;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/reddit/listInbox

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.reddit.listInbox();
  • listMySubscriptionsLists the communities the signed-in caller has joined.

    Arguments

    NameTypeRequired
    opts{ limit?: number; after?: string }No

    Returns RedditMySubscriptions

    interface RedditSubredditInfo {
      id: string;                  // "t5_…"
      name: string;                // canonical casing, what every other function takes
      title: string;
      description: string | null;  // the short public description
      sidebar: string | null;      // the long markdown sidebar
      subscribers: number | null;
      activeUsers: number | null;
      createdAt: string;
      type: string;                // public, private, restricted, archived, gold_only, …
      over18: boolean;
      quarantined: boolean;
      url: string;
      iconUrl: string | null;
      bannerUrl: string | null;
      submissionType: string | null; // "any", "link", "self"
      language: string | null;
      viewer: { subscribed: boolean; moderator: boolean; banned: boolean } | null;
    }
    
    interface RedditMySubscriptions {
      subreddits: RedditSubredditInfo[];
      nextCursor: string | null;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/reddit/listMySubscriptions

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.reddit.listMySubscriptions();
  • listPostFlairsLists the post flairs a community offers, with their ids.

    Arguments

    NameTypeRequired
    subredditstringYes

    Returns RedditPostFlairs

    interface RedditPostFlair {
      id: string;                  // the flair template id submitPost takes
      text: string;
      textEditable: boolean;       // the poster may write their own text on it
      modOnly: boolean;
      allowableContent: string | null; // "all", "text", "emoji"
      backgroundColor: string | null;
      textColor: string | null;    // "light" | "dark"
      cssClass: string | null;
    }
    
    interface RedditPostFlairs {
      subreddit: string;
      posterCanChoose: boolean;    // false = posters cannot pick a flair here; flairs is empty
      flairs: RedditPostFlair[];
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/reddit/listPostFlairs

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.reddit.listPostFlairs("webscraping");
  • listSavedLists the posts and comments the signed-in caller has saved.

    Arguments

    NameTypeRequired
    opts{ limit?: number; after?: string }No

    Returns RedditSavedList

    interface RedditPost {
      id: string;                  // fullname "t3_…", what getPost, vote, savePostOrComment and postComment take
      title: string;
      author: string | null;       // null = deleted account
      subreddit: string;
      permalink: string;           // the discussion
      url: string;                 // what the post points AT; the permalink for a self post
      domain: string | null;
      isSelfPost: boolean;
      selfText: string | null;     // markdown body of a self post
      score: number;
      upvoteRatio: number | null;
      numComments: number;
      createdAt: string;
      editedAt: string | null;
      flair: string | null;        // the flair's display text, submitPost's `flairText`
      flairId: string | null;      // the flair TEMPLATE id, submitPost's `flairId` (same id listPostFlairs returns)
      over18: boolean;
      spoiler: boolean;
      stickied: boolean;           // pinned by the moderators
      locked: boolean;
      archived: boolean;
      removed: string | null;      // reddit's removal reason, e.g. "moderator"; null = still up
      thumbnail: string | null;
      isVideo: boolean;
      viewer: { vote: "up" | "down" | null; saved: boolean; hidden: boolean } | null; // null when not signed in
    }
    
    interface RedditComment {
      id: string;                  // fullname "t1_…"
      author: string | null;       // null = deleted account
      body: string;                // markdown as written (plain rendered text from getPost)
      score: number | null;        // null while reddit hides a new comment's score
      createdAt: string;
      editedAt: string | null;
      permalink: string;           // this exact reply
      parentId: string;            // "t1_…" for a reply, "t3_…" for a top-level comment
      postId: string;              // "t3_…" of the thread
      subreddit: string;
      depth: number;
      isSubmitter: boolean;        // written by the thread's own author
      stickied: boolean;
      distinguished: string | null; // "moderator", "admin"
      replies: RedditComment[];    // nested, as reddit nests them
      moreReplies: { count: number; ids: string[] } | null;
      viewer: { vote: "up" | "down" | null; saved: boolean } | null;
    }
    
    type RedditSavedItem =
      | { kind: "post"; post: RedditPost }
      | { kind: "comment"; comment: RedditComment; postTitle: string | null; postPermalink: string | null };
    
    interface RedditSavedList {
      items: RedditSavedItem[];    // newest save first
      nextCursor: string | null;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/reddit/listSaved

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.reddit.listSaved();
  • listWikiPagesLists the pages of one subreddit's wiki.

    Arguments

    NameTypeRequired
    subredditstring | { subreddit: string }Yes

    Returns RedditWikiPages | RedditWikiAbsent

    interface RedditWikiPages {
      state: "ok";
      subreddit: string;
      pages: string[];
    }
    
    interface RedditWikiAbsent {
      state: "no_such_community" | "community_unavailable" | "private" | "not_viewable" | "page_not_found";
      subreddit: string;
      page?: string;
      reason: string | null;       // reddit's own word, e.g. "MAY_NOT_VIEW"
      pages?: string[];            // on page_not_found: the pages that do exist
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/reddit/listWikiPages

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.reddit.listWikiPages("AskHistorians");
  • searchCommentsSearches the text of comments rather than posts, site-wide or narrowed to one subreddit, returning each match with its body, author, score, the…

    Arguments

    NameTypeRequired
    querystring | { query: string; sort?: "relevance" | "new" | "top"; subreddit?: string; cursor?: string }Yes

    Returns RedditCommentSearch

    interface RedditCommentHit {
      id: string;                  // "t1_…"
      author: string | null;
      body: string;                // plain text
      score: number | null;
      createdAt: string | null;    // ISO
      permalink: string | null;    // to this exact reply
      parentId: string | null;     // "t1_…" when it answers a comment
      subreddit: string;
      thread: { id: string; title: string; permalink: string | null; score: number | null; numComments: number | null };
    }
    
    interface RedditCommentSearch {
      query: string;
      sort: "relevance" | "new" | "top";
      subreddit: string | null;    // the community it was scoped to, or null for site-wide
      comments: RedditCommentHit[];
      nextCursor: string | null;   // pass back as `cursor`
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/reddit/searchComments

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.reddit.searchComments({ query: "web scraping", sort: "new" });
  • searchSubredditsFinds communities by topic.

    Arguments

    NameTypeRequired
    querystring | {query: string, limit?: number, after?: string}Yes

    Returns RedditSubredditSearchResult

    interface RedditSubredditInfo {
      id: string;                  // "t5_…"
      name: string;                // canonical casing, what every other function takes
      title: string;
      description: string | null;  // the short public description
      sidebar: string | null;      // the long markdown sidebar
      subscribers: number | null;
      activeUsers: number | null;
      createdAt: string;
      type: string;                // public, private, restricted, archived, gold_only, …
      over18: boolean;
      quarantined: boolean;
      url: string;
      iconUrl: string | null;
      bannerUrl: string | null;
      submissionType: string | null; // "any", "link", "self"
      language: string | null;
      viewer: { subscribed: boolean; moderator: boolean; banned: boolean } | null;
    }
    
    interface RedditSubredditSearchResult {
      query: string;
      subreddits: RedditSubredditInfo[];
      nextCursor: string | null;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/reddit/searchSubreddits

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.reddit.searchSubreddits("buildapcsales");
  • searchUsersFinds redditors by name, a partial or remembered username goes in, matching accounts come out with their name, karma and creation date.

    Arguments

    NameTypeRequired
    querystring | { query: string; limit?: number; after?: string }Yes

    Returns RedditUserSearch

    interface RedditUserInfo {
      id: string;                  // "t2_…"
      name: string;
      createdAt: string;
      linkKarma: number;
      commentKarma: number;
      totalKarma: number;
      iconUrl: string | null;
      description: string | null;  // the profile's own blurb
      isEmployee: boolean;
      isModerator: boolean;
      verified: boolean;
      hasPremium: boolean;
      suspended: boolean;
      over18Profile: boolean;
      url: string;
    }
    
    interface RedditUserSearch {
      query: string;
      users: RedditUserInfo[];
      nextCursor: string | null;   // pass back as `after`
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/reddit/searchUsers

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.reddit.searchUsers("spez");
Act 18
  • blockUserBlocks a redditor for the signed-in caller, hiding their posts, comments and messages.

    Arguments

    NameTypeRequired
    userstringYes

    Returns RedditBlockResult

    interface RedditBlockResult { user: string; blocked: true }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/reddit/blockUser

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.reddit.blockUser("<user>");
  • createSubredditCreates a new community owned by the signed-in caller.

    Arguments

    NameTypeRequired
    input{ name: string; description?: string; type?: "public" | "restricted" | "private"; nsfw?: boolean }Yes

    Returns RedditNewCommunity

    interface RedditNewCommunity {
      id: string;                  // "t5_…"
      name: string;
      url: string;
      type: "public" | "restricted" | "private";
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/reddit/createSubreddit

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.reddit.createSubreddit({});
  • deletePostOrCommentDeletes the signed-in caller's own post or comment.

    Arguments

    NameTypeRequired
    thingstring | { thing: string }Yes

    Returns { id: string; deleted: true }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/reddit/deletePostOrComment

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.reddit.deletePostOrComment("<thing>");
  • editPostOrCommentEdits the text of the signed-in caller's own post or comment.

    Arguments

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

    Returns RedditEdited

    interface RedditPost {
      id: string;                  // fullname "t3_…", what getPost, vote, savePostOrComment and postComment take
      title: string;
      author: string | null;       // null = deleted account
      subreddit: string;
      permalink: string;           // the discussion
      url: string;                 // what the post points AT; the permalink for a self post
      domain: string | null;
      isSelfPost: boolean;
      selfText: string | null;     // markdown body of a self post
      score: number;
      upvoteRatio: number | null;
      numComments: number;
      createdAt: string;
      editedAt: string | null;
      flair: string | null;        // the flair's display text, submitPost's `flairText`
      flairId: string | null;      // the flair TEMPLATE id, submitPost's `flairId` (same id listPostFlairs returns)
      over18: boolean;
      spoiler: boolean;
      stickied: boolean;           // pinned by the moderators
      locked: boolean;
      archived: boolean;
      removed: string | null;      // reddit's removal reason, e.g. "moderator"; null = still up
      thumbnail: string | null;
      isVideo: boolean;
      viewer: { vote: "up" | "down" | null; saved: boolean; hidden: boolean } | null; // null when not signed in
    }
    
    interface RedditComment {
      id: string;                  // fullname "t1_…"
      author: string | null;       // null = deleted account
      body: string;                // markdown as written (plain rendered text from getPost)
      score: number | null;        // null while reddit hides a new comment's score
      createdAt: string;
      editedAt: string | null;
      permalink: string;           // this exact reply
      parentId: string;            // "t1_…" for a reply, "t3_…" for a top-level comment
      postId: string;              // "t3_…" of the thread
      subreddit: string;
      depth: number;
      isSubmitter: boolean;        // written by the thread's own author
      stickied: boolean;
      distinguished: string | null; // "moderator", "admin"
      replies: RedditComment[];    // nested, as reddit nests them
      moreReplies: { count: number; ids: string[] } | null;
      viewer: { vote: "up" | "down" | null; saved: boolean } | null;
    }
    
    interface RedditEdited {
      kind: "post" | "comment";    // which of the two below is set
      post: RedditPost | null;
      comment: RedditComment | null;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/reddit/editPostOrComment

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.reddit.editPostOrComment({});
  • followUserFollows or unfollows a redditor as the signed-in caller, so their posts reach the caller's feed.

    Arguments

    NameTypeRequired
    userstring | { name: string; follow?: boolean }Yes

    Returns RedditFollowResult

    interface RedditFollowResult { user: string; following: boolean }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/reddit/followUser

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.reddit.followUser("<user>");
  • hidePostHides or un-hides a post from the signed-in caller's feeds.

    Arguments

    NameTypeRequired
    poststring | { id: string; hidden?: boolean }Yes

    Returns RedditHideResult

    interface RedditHideResult { id: string; hidden: boolean }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/reddit/hidePost

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.reddit.hidePost("<post>");
  • joinSubredditJoins a community as the signed-in caller, so its posts reach their home feed.

    Arguments

    NameTypeRequired
    subredditstringYes

    Returns RedditSubscription

    interface RedditSubscription { subreddit: string; subscribed: boolean }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/reddit/joinSubreddit

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.reddit.joinSubreddit("<subreddit>");
  • leaveSubredditLeaves a community the signed-in caller has joined.

    Arguments

    NameTypeRequired
    subredditstringYes

    Returns RedditSubscription

    interface RedditSubscription { subreddit: string; subscribed: boolean }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/reddit/leaveSubreddit

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.reddit.leaveSubreddit("<subreddit>");
  • postCommentComments on a post as the signed-in caller and returns the new comment's permalink.

    Arguments

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

    Returns RedditComment

    interface RedditComment {
      id: string;                  // fullname "t1_…"
      author: string | null;       // null = deleted account
      body: string;                // markdown as written (plain rendered text from getPost)
      score: number | null;        // null while reddit hides a new comment's score
      createdAt: string;
      editedAt: string | null;
      permalink: string;           // this exact reply
      parentId: string;            // "t1_…" for a reply, "t3_…" for a top-level comment
      postId: string;              // "t3_…" of the thread
      subreddit: string;
      depth: number;
      isSubmitter: boolean;        // written by the thread's own author
      stickied: boolean;
      distinguished: string | null; // "moderator", "admin"
      replies: RedditComment[];    // nested, as reddit nests them
      moreReplies: { count: number; ids: string[] } | null;
      viewer: { vote: "up" | "down" | null; saved: boolean } | null;
    }

    HTTP endpoint

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

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.reddit.postComment({});
  • replyToCommentReplies to a comment as the signed-in caller and returns the new reply's permalink.

    Arguments

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

    Returns RedditComment

    interface RedditComment {
      id: string;                  // fullname "t1_…"
      author: string | null;       // null = deleted account
      body: string;                // markdown as written (plain rendered text from getPost)
      score: number | null;        // null while reddit hides a new comment's score
      createdAt: string;
      editedAt: string | null;
      permalink: string;           // this exact reply
      parentId: string;            // "t1_…" for a reply, "t3_…" for a top-level comment
      postId: string;              // "t3_…" of the thread
      subreddit: string;
      depth: number;
      isSubmitter: boolean;        // written by the thread's own author
      stickied: boolean;
      distinguished: string | null; // "moderator", "admin"
      replies: RedditComment[];    // nested, as reddit nests them
      moreReplies: { count: number; ids: string[] } | null;
      viewer: { vote: "up" | "down" | null; saved: boolean } | null;
    }

    HTTP endpoint

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

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.reddit.replyToComment({});
  • reportPostOrCommentReports a post or comment to a community's moderators, as the signed-in caller, under one of that community's rules or Reddit's site-wide reasons.

    Arguments

    NameTypeRequired
    input{ thing: string; rule?: string; siteReason?: string; reason?: string }Yes

    Returns { id: string; reported: true }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/reddit/reportPostOrComment

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.reddit.reportPostOrComment({});
  • savePostOrCommentSaves a post or comment to the signed-in caller's Saved list.

    Arguments

    NameTypeRequired
    idstringYes

    Returns RedditSaveResult

    interface RedditSaveResult { id: string; saved: boolean }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/reddit/savePostOrComment

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.reddit.savePostOrComment("<id>");
  • sendDirectMessageSends a direct message (Reddit chat) from the signed-in caller to another redditor.

    Arguments

    NameTypeRequired
    input{ to: string; subject?: string; text: string }Yes

    Returns { to: string; recipientId: string; sent: true }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/reddit/sendDirectMessage

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.reddit.sendDirectMessage({});
  • setProfilePictureUploads an image as the signed-in caller's profile picture.

    Arguments

    NameTypeRequired
    input{ image: { base64: string; mimeType: string } | { url: string } } | { reset: true }Yes

    Returns { iconUrl: string }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/reddit/setProfilePicture

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.reddit.setProfilePicture({});
  • submitPostPosts to a community as the signed-in caller.

    Arguments

    NameTypeRequired
    input{ subreddit: string; title: string; kind?: "self" | "link" | "image" | "crosspost"; text?: string; url?: string; image?: { base64: string; mimeType: string } | { url: string }; crosspostOf?: string; flairId?: string; flairText?: string; nsfw?: boolean; spoiler?: boolean; sendReplies?: boolean }Yes

    Returns RedditNewPost

    interface RedditNewPost {
      id: string;                  // "t3_…"
      permalink: string;
      subreddit: string;
      kind: "self" | "link" | "image" | "crosspost";
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/reddit/submitPost

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.reddit.submitPost({});
  • unsavePostOrCommentRemoves a post or comment from the signed-in caller's Saved list.

    Arguments

    NameTypeRequired
    idstringYes

    Returns RedditSaveResult

    interface RedditSaveResult { id: string; saved: boolean }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/reddit/unsavePostOrComment

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.reddit.unsavePostOrComment("<id>");
  • updateProfileChanges the signed-in caller's public profile.

    Arguments

    NameTypeRequired
    input{ displayName?: string; about?: string }Yes

    Returns RedditProfileText

    interface RedditProfileText {
      displayName: string;         // "" when unset
      about: string;               // the profile bio; "" when unset
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/reddit/updateProfile

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.reddit.updateProfile({});
  • voteUpvotes, downvotes or clears the caller's vote on a post or a comment, as the signed-in caller.

    Arguments

    NameTypeRequired
    opts{ id: string; direction: "up" | "down" | "none" }Yes

    Returns RedditVoteResult

    interface RedditVoteResult { id: string; vote: "up" | "down" | null }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/reddit/vote

    Call it

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

Use it from code