# Reddit API — subreddit posts, comments, search, user profiles, trending & community data from reddit.com (no account required)

> Posts in a subreddit, ranked by `sort`. Returns title/author/score/comment-count. Supports deep paging (`page`) and `flair` filtering.
> ReefAPI engine `reddit` · 10 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/reddit/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed or blocked calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /reddit/v1/subreddit_posts — 1 credit
Posts in a subreddit, ranked by `sort`. Returns title/author/score/comment-count. Supports deep paging (`page`) and `flair` filtering.

**Parameters:**
- `subreddit` (string, required) — Subreddit name (without 'r/').
- `sort` (enum, optional, default "hot") — How posts are ranked. [one of: hot, new, top, rising, controversial]
- `time` (enum, optional, default "day") — Time window — applies ONLY when sort = top or controversial. [one of: hour, day, week, month, year, all]
- `limit` (integer, optional, default 10) — How many posts to return (1–100).
- `flair` (string, optional) — Filter to one post flair, e.g. 'Discussion' (case-insensitive, live source only).
- `source` (enum, optional, default "auto") — Which Reddit data source to use — 'auto' picks the best source automatically. [one of: auto, live, arctic, pullpush]
- `page` (integer, optional, default 1) — Deep paging: page 2 returns the NEXT batch after page 1 (server chains cursors for you, 1–20). Live source only — archive sources page via after_utc/before_utc.
- `cursor` (string, optional) — Next page: pass the previous response's meta.pagination.next_cursor (the 'Next' button does this automatically).

**Returns:** posts[]{title, author, score, num_comments, created_utc, url, id}

**Example request body:**
```json
{
  "subreddit": "python",
  "limit": 10
}
```

### POST /reddit/v1/post_comments — 1 credit
Threaded comments for a post. Returns author/body/score per comment.

**Parameters:**
- `post_id` (string, required) — Post ID or full Reddit URL.
- `sort` (enum, optional, default "top") — Comment ordering. [one of: top, new, controversial, old, qa]
- `limit` (integer, optional, default 50) — How many comments (1–500).
- `depth` (integer, optional, default 10) — Comment-tree depth (1–50).
- `source` (enum, optional, default "auto") — Which Reddit data source to use — 'auto' picks the best source automatically. [one of: auto, live, arctic, pullpush]

**Returns:** comments[]{author, body, score, created_utc, depth, id, replies[]}; more_ids[] + has_more (feed more_ids into load_more_comments for the full tree)

### POST /reddit/v1/search — 1 credit
Search posts, comments, or users by `q` and/or `subreddit`/`author`. Returns results[]. Cursor pagination + `flair` filter apply on the live source.

**Parameters:**
- `q` (string, optional) — Search text. Provide `q` and/or `subreddit`/`author`.
- `subreddit` (string, optional) — Limit the search to one subreddit (optional).
- `author` (string, optional) — Limit to one author's content (optional).
- `type` (enum, optional, default "post") — What to search for. [one of: post, comment, user]
- `sort` (enum, optional, default "relevance") — Result ordering. [one of: relevance, new, top, comments]
- `limit` (integer, optional, default 10) — How many results (1–100).
- `after_utc` (integer, optional) — Only results AFTER this unix time (optional).
- `before_utc` (integer, optional) — Only results BEFORE this unix time (optional).
- `flair` (string, optional) — Filter to one post flair, e.g. 'Discussion' (case-insensitive, live source only).
- `source` (enum, optional, default "auto") — Which Reddit data source to use — 'auto' picks the best source automatically. [one of: auto, live, arctic, pullpush]
- `page` (integer, optional, default 1) — Deep paging: page 2 returns the NEXT batch after page 1 (server chains cursors for you, 1–20). Live source only — archive sources page via after_utc/before_utc.
- `cursor` (string, optional) — Next page: pass the previous response's meta.pagination.next_cursor (the 'Next' button does this automatically).

**Returns:** results[]{title, author, subreddit, score, created_utc, url, id}

**Example request body:**
```json
{
  "subreddit": "python",
  "limit": 10
}
```

### POST /reddit/v1/user — 1 credit
User profile or content. kind=about returns karma/profile; submitted/comments list items (with deep paging).

**Parameters:**
- `username` (string, required) — Reddit username (without 'u/').
- `kind` (enum, optional, default "about") — What to return. [one of: about, submitted, comments]
- `limit` (integer, optional, default 25) — How many items (for submitted/comments, 1–100).
- `sort` (enum, optional, default "new") — Ordering (for submitted/comments). [one of: new, top, hot]
- `source` (enum, optional, default "auto") — Which Reddit data source to use — 'auto' picks the best source automatically. [one of: auto, live, arctic, pullpush]
- `page` (integer, optional, default 1) — Deep paging: page 2 returns the NEXT batch after page 1 (server chains cursors for you, 1–20). Live source only — archive sources page via after_utc/before_utc.
- `cursor` (string, optional) — Next page: pass the previous response's meta.pagination.next_cursor (the 'Next' button does this automatically).

**Returns:** user{...} or items[] (depends on kind)

**Example request body:**
```json
{
  "username": "spez",
  "kind": "about"
}
```

### POST /reddit/v1/subreddit_about — 1 credit
Subreddit metadata: subscribers, description, created date, etc.

**Parameters:**
- `subreddit` (string, required) — Subreddit name (without 'r/').
- `source` (enum, optional, default "auto") — Which Reddit data source to use — 'auto' picks the best source automatically. [one of: auto, live, arctic, pullpush]

**Returns:** subreddit{subscribers, title, public_description, created_utc, over18}

**Example request body:**
```json
{
  "subreddit": "python"
}
```

### POST /reddit/v1/communities — 1 credit
Search subreddits by name/keyword — find communities matching a term, with each one's subscribers, title, description and over-18 flag.

**Parameters:**
- `q` (string, required) — Name or keyword to search subreddits for.
- `limit` (integer, optional, default 25) — Max communities to return (1–100).

**Returns:** communities[]{name, title, subscribers, public_description, over18, created_utc}

**Example request body:**
```json
{
  "q": "python"
}
```

### POST /reddit/v1/trending — 2 credits
Site-wide discovery — hot/popular posts from r/popular or r/all (what's trending across Reddit right now), or the most-popular communities. No subreddit needed.

**Parameters:**
- `scope` (enum, optional, default "popular") — Which site-wide feed. [one of: popular, all]
- `kind` (enum, optional, default "posts") — Return trending posts or the most-popular communities. [one of: posts, communities]
- `sort` (enum, optional, default "hot") — How posts are ranked. [one of: hot, new, top, rising, controversial]
- `time` (enum, optional, default "day") — Time window — applies ONLY when sort = top or controversial. [one of: hour, day, week, month, year, all]
- `limit` (integer, optional, default 25) — How many to return (1–100).
- `flair` (string, optional) — Filter to one post flair, e.g. 'Discussion' (case-insensitive, live source only).
- `page` (integer, optional, default 1) — Deep paging: page 2 returns the NEXT batch after page 1 (server chains cursors for you, 1–20). Live source only — archive sources page via after_utc/before_utc.
- `cursor` (string, optional) — Next page: pass the previous response's meta.pagination.next_cursor (the 'Next' button does this automatically).
- `source` (enum, optional, default "auto") — Which Reddit data source to use — 'auto' picks the best source automatically. [one of: auto, live, arctic, pullpush]

**Returns:** posts[]{title, author, subreddit, score, num_comments, ...} (kind=posts) OR communities[]{name, title, subscribers, ...} (kind=communities)

**Example request body:**
```json
{
  "scope": "popular",
  "limit": 10
}
```

### POST /reddit/v1/user_search — 2 credits
Find Reddit users by name/keyword — people search. Returns matching profiles with karma. (Same as search with type=user.)

**Parameters:**
- `q` (string, required) — Name or keyword to search users for.
- `limit` (integer, optional, default 25) — How many users to return (1–100).
- `cursor` (string, optional) — Next page: pass the previous response's meta.pagination.next_cursor (the 'Next' button does this automatically).
- `source` (enum, optional, default "auto") — Which Reddit data source to use — 'auto' picks the best source automatically. [one of: auto, live, arctic, pullpush]

**Returns:** results[]{name, id, link_karma, comment_karma, total_karma, created_utc, ...}

**Example request body:**
```json
{
  "q": "python",
  "limit": 10
}
```

### POST /reddit/v1/load_more_comments — 3 credits
Expand the collapsed 'more comments' nodes from a post_comments call — pass that response's more_ids to reveal the rest of the thread (build the FULL comment tree).

**Parameters:**
- `post_id` (string, required) — The post these comments belong to (ID or Reddit URL).
- `more_ids` (string, required) — Comma-separated comment IDs from a post_comments response's more_ids list (or comments[].more_ids).
- `limit` (integer, optional, default 100) — Max collapsed IDs to expand per call (1–100; Reddit caps ~100).
- `sort` (enum, optional, default "top") — Comment ordering. [one of: top, new, controversial, old, qa]
- `source` (enum, optional, default "auto") — Which Reddit data source to use — 'auto' picks the best source automatically. [one of: auto, live, arctic, pullpush]

**Returns:** comments[]{author, body, score, depth, id, ...}, more_ids[] (further collapsed ids)

### POST /reddit/v1/subreddit_extras — 3 credits
Public subreddit extras: the community's rules and its wiki page index/content. (Moderator list is mod-only on Reddit and is not available logged-out.)

**Parameters:**
- `subreddit` (string, required) — Subreddit name (without 'r/').
- `include` (string, optional, default "rules,wiki") — Which extras to return: 'rules', 'wiki', or both (comma-separated).
- `wiki_page` (string, optional) — Fetch ONE wiki page's full content (e.g. 'index', 'faq'). Omit to list available page names.
- `source` (enum, optional, default "auto") — Which Reddit data source to use — 'auto' picks the best source automatically. [one of: auto, live, arctic, pullpush]

**Returns:** rules[]{short_name, description, kind, ...}, wiki_pages[] (names) OR wiki_page{page, content_md, revision_date, ...}

**Example request body:**
```json
{
  "subreddit": "python"
}
```

## More
- Try it live, no code: https://reefapi.com/playground?engine=reddit
- Human docs page: https://reefapi.com/docs/reddit
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt