A Typed Reddit API Client in TypeScript: Zod, Unions, and Safe Parsing (2026)

The Reddit API in TypeScript is just JSON over HTTPS, which means the whole type story is under your control. You declare an interface per response, validate the payload at runtime with a schema, and model the comment tree as a discriminated union so the compiler walks it for you. There is no wrapper to install, no OAuth developer app, and no code generation. A single bearer token from redditapis.com plus your own types gives you a Reddit client that catches shape errors at compile time and malformed payloads at runtime.

Not affiliated with Reddit Inc. redditapis.com is an independent third-party REST proxy for Reddit's API.

---

TL;DR: Own your Reddit types. Declare interfaces for each response, add Zod for runtime validation, model the { kind, data } comment tree as a discriminated union, and brand fullnames so a post id cannot be passed where a comment id belongs. One bearer token, one generic get<T>, full type safety, and no wrapper. Reads cost $0.002 per call (pricing).

What you will build:

• Interfaces for posts, search, users, and communities from the live field names
• A generic get<T> request helper with typed error handling
• Runtime validation with Zod so bad JSON is a caught error
• A discriminated-union comment tree with an exhaustive walk
• Branded types for fullnames and type-safe query parameters

Cost: $0.002 per read call. Free credit at signup. No card required.

---

Why Own Your Types in 2026

The historical reason to install snoowrap in a TypeScript project was that it shipped types. But bundled types are only as good as their fit to the response you actually receive, and snoowrap's are tied to Reddit's older OAuth API shapes on a package that has not shipped a meaningful release in years. When the API underneath moves, bundled types drift from reality and the compiler confidently lies to you. Developers feel this when they go looking for a current wrapper and find the shelf bare:

Rohit Dasu

@rohitdasudotcom

Hi twitter 𝕏 developer community, is there any good wrapper package for reddit API for js/nodejs? I got to know about snoowrap. But it was last published 3 years ago. Let me know any updated packages that is good. Thanks :)

Owning your interfaces flips the relationship, and it buys three concrete things:

• No silent drift. You write the type from the exact JSON you receive, so it cannot change without a compile error pointing at the code that cares.
• Exact fit. You control every field name and every optionality decision, instead of inheriting a wrapper's guess.
• Zero code generation. An interface plus a generic request helper is the whole client, with no build tool in the loop.

TypeScript's structural typing, documented in the TypeScript handbook and its narrowing guide, makes this cheap. The response is standard JSON parsed through the web Response API, so there is nothing exotic to model. Redditapis exposes a stable bearer-token REST interface, so there is no OAuth app to register and no token lifecycle to type around. This tutorial builds the typed client the wrappers promised, with your own interfaces and $0.002 per read call (pricing).

For the plain no-wrapper version of the client, see the Node.js and TypeScript tutorial, and for the runtime that needs no build step at all, the Bun native-fetch client.

---

Setup: One Key, Zero OAuth

The credential story is one bearer token. Generate it at signup, export it, and read it from process.env:

export REDDITAPI_KEY="YOUR_API_KEY"
npm install zod   # for runtime validation, later in the guide

The base URL is https://api.redditapis.com and the key goes in the Authorization: Bearer header on every request. There is no client ID, no client secret, and no refresh loop. Keep the key server-side and never ship it to the browser, because a bearer token in client-side code is readable by anyone who opens dev tools. For how keys and auth work, see how to get a Reddit API key and the authentication overview.

---

Interfaces for Every Response Shape

Start from the live field names, not from a wrapper's idea of them. A read returns { posts: [...], after }, and each post carries the fields below. Declaring the interface once is the foundation every other type builds on:

export interface RedditPost {
  id: string;
  name: string;          // fullname, e.g. "t3_abc123"
  title: string;
  author: string;
  subreddit: string;
  permalink: string;
  url: string;
  upvotes: number;
  comments: number;
  upvote_ratio: number;
  over_18: boolean;
  is_self: boolean;
  created_utc: number;
}

export interface PostsResponse {
  posts: RedditPost[];
  after: string | null;
}

export interface RedditUser {
  name: string;
  id: string;
  fullname: string;
  link_karma: number;
  comment_karma: number;
  total_karma: number;
  is_employee: boolean;
  verified: boolean;
  created_utc: number;
}

The single most common typing mistake is copying field names from an old tutorial: the live response uses upvotes and comments, not ups or num_comments. Typing from the real payload avoids a whole class of undefined bugs. Developers reach for a library precisely to skip this step, and one recurring habit is grabbing whatever wrapper looks easiest instead of owning the shape:

Jaydeep

@_jaydeepkarale

REDDIT is a Goldmine of data🪙🪙🪙 There's thousands of TBs of useful and not so useful data being generated on the platform. This data can be scraped and used for data analysis, building practice machine learning projects and numerous other applications. PRAW i.e. the Python… Show more

The full field reference is in the Reddit data API overview.

---

A Generic get Helper with Typed Errors

One generic request function ties every interface together, using TypeScript generics. It attaches the header, builds the query string, narrows the return type, and gives you a single place to handle non-2xx responses:

const BASE = "https://api.redditapis.com";
const KEY = process.env.REDDITAPI_KEY!;

export class RedditApiError extends Error {
  constructor(public status: number, public body: string) {
    super(`Reddit API ${status}: ${body}`);
  }
}

async function get<T>(path: string, params: Record<string, string> = {}): Promise<T> {
  const qs = new URLSearchParams(params).toString();
  const res = await fetch(`${BASE}${path}${qs ? `?${qs}` : ""}`, {
    headers: { Authorization: `Bearer ${KEY}` },
  });
  if (!res.ok) throw new RedditApiError(res.status, await res.text());
  return res.json() as Promise<T>;
}

const { posts } = await get<PostsResponse>("/api/reddit/posts", {
  subreddit: "typescript", sort: "top", limit: "10",
});

A typed error class lets callers catch and switch on err.status instead of parsing strings. get<T> gives autocomplete on the result and compile-time safety on field names. Because every endpoint returns the same JSON-over-HTTPS shape, this one function covers posts, search, users, and communities. The r/node community trades exactly these "how should I structure the data layer" questions that a typed helper settles:

r/

r/node·u/Intelligent_Camp_762

Your internal engineering knowledge base that writes and updates itself from your GitHub repos

00

Open on Reddit

---

Runtime Validation with Zod

TypeScript interfaces are erased at compile time, so they check nothing about the JSON you actually receive. If the payload is malformed, a bad field surfaces as undefined three functions downstream, far from the cause. A schema library like Zod, whose source lives at github.com/colinhacks/zod, parses the response and narrows it to your type, so a bad payload is a caught error at the boundary:

import { z } from "zod";

const RedditPostSchema = z.object({
  id: z.string(),
  name: z.string(),
  title: z.string(),
  author: z.string(),
  subreddit: z.string(),
  permalink: z.string(),
  upvotes: z.number(),
  comments: z.number(),
  upvote_ratio: z.number(),
  created_utc: z.number(),
});

const PostsResponseSchema = z.object({
  posts: z.array(RedditPostSchema),
  after: z.string().nullable(),
});

async function getPosts(subreddit: string): Promise<z.infer<typeof PostsResponseSchema>> {
  const raw = await get<unknown>("/api/reddit/posts", { subreddit, limit: "25" });
  return PostsResponseSchema.parse(raw); // throws ZodError on a shape mismatch
}

z.infer derives the TypeScript type from the schema, so you define the shape once and get both the runtime check and the static type. The parse throws a ZodError that names the exact field that failed, which turns "why is this undefined" into a precise, early failure. For a service that runs unattended, this is the difference between a caught boundary error and a silent corruption that surfaces hours later. Use safeParse when you want a result object instead of a throw. The r/node community discusses these robustness patterns often:

r/

r/node·u/john_dumb_bear

How do I implement a push API?

00

Open on Reddit

---

A Discriminated Union for the Comment Tree

The comment tree is where naive typing breaks down. The comments endpoint returns { post, comments, after }, and each node in comments is a { kind, data } object where kind is t1 for a real comment or more for a load-more stub. That is a textbook discriminated union: switch on kind and TypeScript narrows data to the right shape:

interface CommentData {
  id: string;
  author: string;
  body: string;
  score: number;
  created_utc: number;
  replies?: CommentNode[];
}
interface MoreData {
  count: number;
  children: string[];
}

type CommentNode =
  | { kind: "t1"; data: CommentData }
  | { kind: "more"; data: MoreData };

function walk(nodes: CommentNode[], depth = 0): void {
  for (const node of nodes) {
    switch (node.kind) {
      case "t1":
        console.log(`${"  ".repeat(depth)}${node.data.author}: ${node.data.body.slice(0, 60)}`);
        if (node.data.replies) walk(node.data.replies, depth + 1);
        break;
      case "more":
        console.log(`${"  ".repeat(depth)}(+${node.data.count} more)`);
        break;
      default: {
        const _exhaustive: never = node; // compile error if a kind is unhandled
        return _exhaustive;
      }
    }
  }
}

The never branch is the payoff: if Reddit adds a node kind and you forget to handle it, the assignment to _exhaustive fails to compile, so the type system tells you exactly where to update. This is the pattern discriminated unions exist for, and modeling the comment tree this way turns a recursive, easy-to-mistype structure into a walk the compiler verifies. The comments guide covers the endpoint parameters, and how to build a Reddit MCP server uses the same tree in an agent tool.

---

Branded Types for Fullnames and IDs

A fullname is a prefixed id like t3_abc123 for a post or t1_def456 for a comment. Typed as a plain string, nothing stops you passing a post fullname where a comment fullname is expected, and the mistake compiles cleanly and fails at runtime. A branded type closes that gap:

type PostFullname = string & { readonly __brand: "PostFullname" };
type CommentFullname = string & { readonly __brand: "CommentFullname" };

function asPostFullname(s: string): PostFullname {
  if (!s.startsWith("t3_")) throw new Error(`not a post fullname: ${s}`);
  return s as PostFullname;
}

function fetchComments(post: PostFullname) { /* ... */ }

const p = asPostFullname("t3_abc123");
fetchComments(p);            // ok
// fetchComments("t1_def456"); // compile error: not a PostFullname

The brand exists only in the type system and is erased at runtime, so there is no cost, but the compiler now rejects a whole class of id mix-ups. Pair the brand with a validator like asPostFullname and you also get a runtime guard that the string really has the t3_ prefix. The data API overview lists every id prefix, and the Node.js tutorial shows how fullnames flow from reads into writes.

---

Type-Safe Query Parameters

Endpoints accept a small, fixed vocabulary for sort and t, and a typo there is another runtime-only failure. Union literal types make the compiler enforce the vocabulary:

type PostSort = "new" | "hot" | "top" | "rising" | "controversial" | "best";
type TimeWindow = "hour" | "day" | "week" | "month" | "year" | "all";

interface PostsParams {
  subreddit: string;
  sort?: PostSort;
  t?: TimeWindow;    // only meaningful when sort is "top" or "controversial"
  limit?: number;    // 1 to 100
  after?: string;
}

function buildQuery(params: PostsParams): Record<string, string> {
  const out: Record<string, string> = { subreddit: params.subreddit };
  if (params.sort) out.sort = params.sort;
  if (params.t) out.t = params.t;
  if (params.limit) out.limit = String(params.limit);
  if (params.after) out.after = params.after;
  return out;
}

Now sort: "toop" is a compile error, not a silently-ignored parameter that returns the wrong ordering. The literal unions double as documentation: your editor autocompletes the valid values. This is the small, high-leverage typing that catches the mistakes that otherwise only show up in a manual test. For the search-specific vocabulary, which differs slightly, see the Reddit search API tutorial.

---

Typed Pagination

Pagination combines the interfaces above into a fully typed loop. The after cursor is string | null, and the loop stops when it comes back null:

async function fetchAll(params: PostsParams, max = 300): Promise<RedditPost[]> {
  const all: RedditPost[] = [];
  let after: string | null = null;
  while (all.length < max) {
    const page = await get<PostsResponse>("/api/reddit/posts", buildQuery({ ...params, after: after ?? undefined }));
    all.push(...page.posts);
    if (!page.after || page.posts.length === 0) break;
    after = page.after;
  }
  return all.slice(0, max);
}

The typed cursor means the compiler reminds you the loop can end. This is the same pattern the plain clients use, now with the return type pinned to RedditPost[]. The video below covers the fetch fundamentals underneath the typed wrapper:

For the pagination pattern across languages, see the pagination guide, and for streaming instead of batch, webhooks versus polling.

---

Types That Pay Off in the 2026 AI-Agent Era

Strong types matter most where a value crosses a boundary you do not control, and an AI agent tool is exactly that boundary. When a model calls a Reddit read tool, the JSON it hands back becomes context the model reasons over, so a validated, well-typed response is the difference between a reliable tool and one that occasionally passes garbage into a prompt. A Zod parse at the tool boundary guarantees the agent only ever sees the shape you declared. Reddit is one of the most-cited sources in AI answer engines, which is why live Reddit reads are a common agent capability. For the agent-facing packaging, see the Reddit API for AI agents guide and how to build a Reddit MCP server.

The discriminated-union comment tree pays off here too. An agent that summarizes a thread walks the same { kind, data } union, and the exhaustive never check means a future API change surfaces as a build failure rather than a silent gap in what the agent reads.

---

What the Reddit API Costs for a TypeScript App

Cost depends on which endpoints you call, not on a per-seat subscription. Reads are $0.002 each, votes $0.005, comments and logins $0.012, and direct messages $0.025 (full per-call pricing). There is no monthly minimum and no platform call cap:

TypeScript scenario	Monthly calls	Approx cost
Typed subreddit monitor	~15,000 reads	about $30 (pricing)
Agent tool (50,000 reads/month)	50,000 reads	about $100 (pricing)
Weekend project (a few hundred reads)	~300 reads	covered by free credit (pricing)

Most typed Reddit clients are read-heavy, which is the shape usage pricing fits: $0.002 per read for exactly the calls you make (pricing). Reddit's own commercial tier starts at a $12,000 per year minimum (Reddit's Data API terms), which is why a per-call REST endpoint is the pragmatic path for a TypeScript app not yet at massive scale. Model your exact numbers with the cost calculator and compare access paths on the pricing page. The r/node community regularly weighs these build-versus-buy tradeoffs:

r/

r/node·u/MrJami_

What else can I do to to get a bigger community?

00

Open on Reddit

---

Deriving Types from Zod, Not Duplicating Them

A common mistake when you add Zod is writing the schema and the interface separately, which means two sources of truth that drift the moment someone edits one. The fix is to make the schema the single source and derive the type from it with z.infer. You write the shape once, as a schema, and TypeScript reads the static type off it for free:

import { z } from "zod";

const RedditUserSchema = z.object({
  name: z.string(),
  id: z.string(),
  fullname: z.string(),
  link_karma: z.number(),
  comment_karma: z.number(),
  total_karma: z.number(),
  is_employee: z.boolean(),
  verified: z.boolean(),
  created_utc: z.number(),
});

export type RedditUser = z.infer<typeof RedditUserSchema>; // one source of truth

async function getUser(name: string): Promise<RedditUser> {
  const raw = await get<unknown>(`/api/reddit/user/${encodeURIComponent(name)}`);
  return RedditUserSchema.parse(raw);
}

Now the schema and the type can never disagree, because the type is generated from the schema. When Reddit adds a field you care about, you add it to the schema in one place and the type updates automatically, and any code that relied on the old shape either keeps working or fails to compile at the exact call site that needs attention. This is the discipline that makes runtime validation sustainable rather than a second thing to maintain. For anything you only read some fields of, use .pick to derive a narrower schema, so a summary function that needs only name and total_karma validates just those and stays cheap. The single-source pattern scales from one response to an entire API surface without the drift that separate interfaces invite.

There is a subtle correctness win here too. Because parse runs at the boundary, a field the API marks optional, or one that is occasionally null, surfaces as a schema decision you make explicitly with .optional() or .nullable(), rather than an assumption baked silently into an interface. Modeling optionality honestly at the schema level is what stops the cannot read property of undefined class of bug, because the parse either gives you a value of the declared shape or throws with the field named. The r/node community discusses these robustness patterns whenever a service needs to survive imperfect upstream data.

Handling Errors and Rate Limits with Types

A typed client should type its failures as carefully as its successes. The RedditApiError class from earlier carries a status, so callers can switch on it and react correctly, and a small helper turns the status into a typed outcome your code can pattern-match instead of guessing from a string:

type ReadResult<T> =
  | { ok: true; data: T }
  | { ok: false; status: number; transient: boolean };

async function safeGet<T>(path: string, params?: Record<string, string>): Promise<ReadResult<T>> {
  try {
    return { ok: true, data: await get<T>(path, params) };
  } catch (err) {
    if (err instanceof RedditApiError) {
      const transient = err.status === 429 || err.status >= 500;
      return { ok: false, status: err.status, transient };
    }
    throw err; // a non-API error is a real bug, let it surface
  }
}

A ReadResult<T> union forces the caller to handle both outcomes: the compiler will not let you read .data without first checking .ok, which eliminates the "I forgot this could fail" bug. The transient flag encodes the retry decision in the type, so a caller knows a 429 or 5xx is worth retrying while a 404 is not, without re-deriving that logic. This is the retry ladder from the plain clients, made type-safe: wrap safeGet in a loop that retries while transient is true and attempts remain, and back off between tries. Encoding the transient-versus-fatal distinction in the return type is what keeps error handling consistent across every call site, instead of each one inventing its own idea of what is worth retrying. For the numbers behind a healthy retry budget, see Reddit API rate limits 2026.

Packaging Your Typed Client as a Module

Once the interfaces, the get<T> helper, the schemas, and the error types live together, they form a small module you can reuse across projects or publish. The shape that keeps it clean is a single entry point that exports the client factory and the types, so a consumer imports one thing and gets full autocomplete:

// reddit-client.ts
export interface RedditClient {
  posts(subreddit: string, opts?: PostsParams): Promise<RedditPost[]>;
  search(q: string, opts?: Partial<PostsParams>): Promise<RedditPost[]>;
  user(name: string): Promise<RedditUser>;
  comments(permalink: string): Promise<CommentNode[]>;
}

export function createClient(key: string, base = "https://api.redditapis.com"): RedditClient {
  // close over key + base; each method calls the typed get<T> and parses with Zod
  return { /* posts, search, user, comments */ } as RedditClient;
}

Exposing a RedditClient interface rather than a loose bag of functions means a consumer programs against the interface, and you can swap the implementation, add caching, or mock it in tests without changing a caller. The factory closes over the key and base URL so those are configured once, and every method returns a validated, typed value. This is the difference between a script and a library: a library has a stable surface a caller depends on, and a typed surface is the most valuable kind because the compiler enforces the contract on both sides. If you decide to publish it, the same principles that make the internal module clean, one entry point, exported types, a factory, make it a good package. For the positioning of a published Reddit package, see the typed Reddit npm SDK, and for a portable agent-facing package, the Reddit Agent Skill guide.

The reason to invest in the module shape is longevity. A typed client you own does not go stale the way a bundled wrapper does, because every change is a change you make against a compiler that tells you what else needs to move. Three years from now, a field rename in the API is a one-line schema edit plus a set of compile errors that point at exactly the call sites to update, which is a far better maintenance story than a wrapper whose types no longer match a live response and whose maintainer is not around to fix it. The r/webdev community's long-running debates about which patterns survive capture why owning a small, typed surface beats depending on a large, aging one.

Common TypeScript Typing Mistakes with the Reddit API

A few typing mistakes recur often enough to be worth naming, because each one compiles cleanly and only fails at runtime, which is the worst place to find a type error. The first is copying field names from an old tutorial or a wrapper's types. The live response uses upvotes and comments, so an interface that declares ups and num_comments compiles fine and then hands you undefined at runtime, because those fields simply are not in the payload. The fix is to type from the real response you receive, not from a remembered shape, and a Zod parse catches the mismatch at the boundary the moment it happens rather than three functions later.

The second common mistake is over-trusting optionality. It is tempting to declare every field required because that gives the nicest autocomplete, but a field the API omits on some posts, or returns as null, will then be a lie the compiler believes. A self post and a link post differ in which fields carry content, and a deleted author comes back as a placeholder rather than a real username, so modeling those honestly with .optional() or a union is what keeps the type truthful. The discipline is to let the schema express reality, even when reality is messier than you would like, because a truthful type that admits a field can be absent is far more useful than a tidy type that pretends it never is.

The third mistake is typing the comment tree as a flat array of one shape. The tree mixes real comments with load-more stubs, and both arrive under the same comments array, so a single Comment[] type forces you to guess which fields exist on each element. The discriminated union from earlier is the correct model precisely because it refuses that guess: switch on kind, and the compiler narrows each node to the fields it really has. Any code that walks the tree without the union is one API quirk away from reading a field that does not exist on a more node, and the union turns that latent bug into a compile-time certainty.

A fourth, subtler mistake is treating ids as interchangeable strings. A post fullname and a comment fullname are both strings, so passing one where the other belongs compiles, and the branded-type pattern from earlier is the antidote. It costs nothing at runtime and closes a class of mix-up that otherwise only surfaces when a request returns the wrong thing or a 404. Each of these mistakes shares a root cause: TypeScript's static types describe your intent, not the bytes on the wire, so anywhere the two can diverge, a runtime check is what keeps intent and reality aligned. That is the whole case for pairing owned interfaces with a schema library, and it is why a typed Reddit client that validates at the boundary is more robust than one that trusts the payload. The r/webdev community's recurring debugging threads are full of exactly these erased-type surprises, which is why validation at the edge has become standard practice.

Ship It

A typed Reddit client in TypeScript is not a wrapper you install, it is a handful of interfaces you own plus a schema you validate against. One bearer token, a generic get<T>, Zod at the boundary, a discriminated-union comment tree, and branded fullnames give you a client the compiler checks statically and the schema checks at runtime, with no OAuth app and no code generation.

The whole client is a single module: interfaces from the live field names, a get<T> with a typed error class, Zod schemas with z.infer, a CommentNode union with an exhaustive walk, branded ids, and literal-union params. Every piece is yours, so nothing drifts without a compile error telling you. The investment is small and it compounds: the first hour you spend declaring shapes and wiring a schema is repaid every time the API returns something unexpected and your parse catches it at the boundary instead of your users catching it in production. A typed client is not extra ceremony over a plain one, it is the same client with its failure modes moved from runtime to compile time and its data validated at the one place it enters your program. That is the trade every serious integration eventually makes, and starting with it costs less than retrofitting it later, because a schema written alongside the first request is cheaper than one reverse-engineered from a bug report months in. Generate a key and write your first typed call in about two minutes: sign up for free, no card required, and let the compiler and the schema do the work of keeping your client honest as it grows. The payoff is not visible on day one, when a plain client would also work, but it shows up on the day the API returns a shape you did not expect and your parse turns a silent corruption into a clear, early, named error you can fix before anyone downstream ever sees it. Generate a key and make your first typed call in about two minutes: sign up for free, no card required. For the plain client, see the Node.js and TypeScript tutorial, and to package this as an installable tool, the typed npm SDK positioning.