Communities, discussion threads and their comment trees — search, subreddit listings, posts, users and wikis.
Communities, discussion threads and their comment trees — search, subreddit listings, posts, users and wikis. Five functions are callable, off Reddit's own syndication feed, and they compose into the whole path an agent actually walks: finding which COMMUNITIES cover a topic, qualifying one of them before spending anything on it (may you read it at all, and is anyone still posting), reading that community's own front page under any sort reddit offers (hot, new, top, rising, controversial), searching submissions by topic across the site or inside that community, and reading any one of the threads that returns in full, post and comments.
Domain: reddit.com
Also known as: Reddit, reddit.com, old.reddit.com, subreddit
Call it directly
bowmark.providers.reddit.getSubreddit(name: string): Promise<RedditSubreddit>
bowmark.providers.reddit.getSubredditPosts(input: string | {subreddit: string, sort?: "hot"|"new"|"top"|"rising"|"controversial", time?: "hour"|"day"|"week"|"month"|"year"|"all", limit?: number}): Promise<RedditSubredditPostsResult>
bowmark.providers.reddit.searchSubreddits(query: string | {query: string, limit?: number}): Promise<RedditSubredditSearchResult>
bowmark.providers.reddit.search(query: string | {query: string, subreddit?: string, sort?: "relevance"|"hot"|"top"|"new"|"comments", time?: "hour"|"day"|"week"|"month"|"year"|"all", limit?: number}): Promise<RedditSearchResult>
bowmark.providers.reddit.getPost(ref: string): Promise<RedditThread>Functions
| Function | What it does |
|---|---|
getSubreddit | Reads the facts about ONE Reddit community rather than its content, from a bare name, "r/name" or the community's URL. |
getSubredditPosts | Returns ONE community's own front page — the submissions in a subreddit under a chosen sort, with the same per-post fields search returns (title, author, subreddit, timestamp, a permalink… |
searchSubreddits | Finds Reddit COMMUNITIES by topic — the step before every other function here, and the one an agent cannot skip: Reddit's value is concentrated in communities whose names you would never… |
search | Searches Reddit's submissions for a phrase — across the whole site, or scoped to one community with subreddit — and returns the matching threads with their title, author, subreddit,… |
getPost | Reads one Reddit thread — the submission and the discussion under it — from a thread URL, a t3_… fullname or a bare post id. |
Types
interface RedditSearchPost {
id: string; // reddit fullname, e.g. "t3_1tbuq4g" — pass to getPost
title: string;
author: string | null; // null when the account was deleted
subreddit: string; // bare name, e.g. "webscraping"
permalink: string; // the DISCUSSION on reddit
url: string; // what the post points AT — the article, or the
// permalink itself when it is a self post
isSelfPost: boolean;
selfText: string | null; // the body, for a self post
selfTextHtml: string | null;
createdAt: string;
thumbnail: string | null;
}
interface RedditCommunityAccess {
state: "public" | "private" | "restricted" | "banned" | "unrecognized";
label: string | null; // reddit's OWN word: "private", "banned",
// "premium members only", "forbidden (reddit.com)".
// null when it served the community normally.
readable: boolean; // check THIS before trusting posts/activity
status: number; // what reddit answered with
}
interface RedditCommunityPost {
id: string; // reddit fullname, e.g. "t3_1tbuq4g" — pass to getPost
title: string;
author: string | null; // null when the account was deleted
permalink: string;
createdAt: string;
}
interface RedditSubreddit {
name: string; // reddit's canonical casing, e.g. "CenturyClub"
url: string;
description: string | null; // the moderators' own words — served EVEN when the
// community refuses to be read
iconUrl: string | null;
access: RedditCommunityAccess;
posts: RedditCommunityPost[]; // newest first; empty when not readable
postsRetrieved: number;
newestPostAt: string | null; // the liveness answer
oldestPostAt: string | null;
activityWindowDays: number | null;
postsPerDay: number | null; // measured across that window
windowTruncated: boolean; // true = older posts exist past this window
requests: number;
limits: string[]; // what this surface cannot tell you. Never empty.
// NO subscriber count, NO online count, NO rules, NO creation date, NO display
// title: reddit's syndication surface publishes none of them. See limits.
}
interface RedditCommunityHit {
id: string; // e.g. "t5_318ly"
name: string; // bare name, e.g. "webscraping" — pass to search({subreddit})
title: string; // display title, which OFTEN DIFFERS from the name:
// t5_323rf is named "scrapingtheweb", titled
// "Scraping the web"
url: string;
description: string | null;
createdAt: string;
// NO subscriber count, NO over-18 flag, NO private/restricted marker: reddit's
// syndication surface publishes none of them. See limits.
}
interface RedditSubredditSearchResult {
query: string;
subreddits: RedditCommunityHit[]; // ranked as reddit ranked them
subredditsRetrieved: number;
moreAvailable: boolean; // true = stopped at your limit, reddit had more
requests: number;
limits: string[]; // what this surface cannot tell you. Never empty.
}
interface RedditSearchResult {
query: string; // the arguments are part of the answer — see limits
subreddit: string | null; // null = the whole site
sort: "relevance" | "hot" | "top" | "new" | "comments";
time: "hour" | "day" | "week" | "month" | "year" | "all";
posts: RedditSearchPost[];
postsRetrieved: number;
communities: RedditCommunityHit[]; // reddit injects these into a site-wide search
moreAvailable: boolean; // true = stopped at your limit, reddit had more
requests: number;
limits: string[]; // what this surface cannot tell you. Never empty.
}
interface RedditSubredditPostsResult {
subreddit: string; // the arguments are part of the answer — see limits
sort: "hot" | "new" | "top" | "rising" | "controversial";
time: "hour" | "day" | "week" | "month" | "year" | "all" | null;
// null = this sort has no window, and yours did
// nothing. NOT the same as "all".
posts: RedditSearchPost[]; // the same rows search returns
postsRetrieved: number;
moreAvailable: boolean; // true = stopped at your limit, reddit had more
duplicatesDropped: number; // > 0 = the live ranking moved while we paged, so
// posts may also be MISSING from this result
requests: number;
limits: string[]; // what this surface cannot tell you. Never empty.
}
interface RedditComment {
id: string; // reddit fullname, e.g. "t1_c60mmaf"
author: string | null; // null when the account was deleted
body: string; // readable text
bodyHtml: string; // as reddit published it
permalink: string; // links to this exact reply
createdAt: string;
}
interface RedditThread {
id: string; // e.g. "t3_z1c9z"
permalink: string;
subreddit: string;
title: string;
author: string | null;
createdAt: string;
selfText: string | null; // null for a link post
selfTextHtml: string | null;
comments: RedditComment[]; // FLAT, in reddit's display order — see limits
commentsRetrieved: number;
commentsTruncated: boolean; // true = the discussion continues past these
limits: string[]; // what this surface cannot tell you. Never empty.
}